You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by Radhika Puthiyetath <ra...@citrix.com> on 2012/10/09 08:13:22 UTC
[DOC] Updating Author List File
Hello Community,
We are in the process of updating the Author List for the ASFCS 4.0 documentation.
Request all the amazing documentation contributors to share their name and email id.
As promised, your name will be displayed in the contributors list in the documentation.
Thank you again for all your enthusiasm and hard work towards getting the documentation ready for ASFC 4.0.
Thanks
-Radhika
RE: [DOC] Updating Author List File
Posted by Radhika Puthiyetath <ra...@citrix.com>.
Hi Wido,
We have a file named Author_Group.xml. We must fill in the details of the authors. Getting the credit encourages the people to contribute even more.
Other projects, such as GNOME, gives credit to the contributors.
Also, whenever a query comes to documentation, it is easier to track who contributed.
We can always vote it in/out.
Regards
-Radhika
-----Original Message-----
From: Wido den Hollander [mailto:wido@widodh.nl]
Sent: Tuesday, October 09, 2012 2:46 PM
To: cloudstack-dev@incubator.apache.org
Subject: Re: [DOC] Updating Author List File
On 10/09/2012 08:13 AM, Radhika Puthiyetath wrote:
> Hello Community,
>
> We are in the process of updating the Author List for the ASFCS 4.0 documentation.
>
> Request all the amazing documentation contributors to share their name and email id.
>
> As promised, your name will be displayed in the contributors list in the documentation.
>
> Thank you again for all your enthusiasm and hard work towards getting the documentation ready for ASFC 4.0.
>
While I get the idea, isn't the documentation something that comes from the Apache Software Foundation? (Remember the CLA?)
As a group we are contributing to the project as a group, the CloudStack brings out a new release, not the individual members.
So I'm not sure that we should mention the individual contributors to the documentation, I don't think so.
Wido
> Thanks
> -Radhika
>
Re: [DOC] Updating Author List File
Posted by Noah Slater <ns...@tumbolia.org>.
It might be a nice idea to maintain a THANKS file at the root of the
project, and/or a contributors page on the website or wiki. The docs can
call out to this, as a link. But then we have one place to maintain it.
You're right, it can be a motivating factor to see your name in the
official product, but this applies to code as much as it applies to
documentation. We actually have it set up so that our THANKS file on
CouchDB is automatically generated from Git, using Author and
Signed-Off-By, etc. Let me know if you want more information about that.
On Tue, Oct 9, 2012 at 8:40 PM, Brett Porter <br...@apache.org> wrote:
>
> On 10/10/2012, at 6:11 AM, Jessica Tomechak <je...@gmail.com>
> wrote:
>
> >>> While I get the idea, isn't the documentation something that comes
> >>> from the Apache Software Foundation? (Remember the CLA?)
> >>>
> >>> As a group we are contributing to the project as a group, the
> >>> CloudStack brings out a new release, not the individual members.
> >>>
> >>> So I'm not sure that we should mention the individual contributors to
> >>> the documentation, I don't think so.
> >>>
> >>> Wido
> >>
> >>
> >> Exactly - we've already removed many names from source code and docs.
> >> While we appreciate individuals work it does become unmaintainable over
> >> time, and we are doing this as a community working together.
> >> Radhika you do have a file named Author_Group - and you'll notice
> (unless
> >> someone has recently changed things) that the author is "Apache
> CloudStack".
> >>
> >> If you need to track who contributed it, our revision control system
> has a
> >> wonderful functionality called 'git blame' which is far more accurate
> than
> >> an authors file will ever be.
> >>
> >> Plus there is a policy against this, see:
> >> https://www.apache.org/dev/apply-license.html#contributor-copyright
> >>
> >> --David
> >>
> >
> > David,
> > It doesn't look to me as if that policy applies. We're not adding
> > individual copyrights, just a "thank you for contributing"
> acknowledgment.
> > I'm all in favor of the idea of giving doc contributors some public
> > applause for their efforts. As Radhika said, it's mainly intended to
> > encourage further contribution.
> >
> > I don't worry too much about the issue of maintaining an accurate
> > Acknowledgments list in the future. Anyone who needs an exhaustive view
> of
> > the contributors should look in the commit log, as others have noted.
> > Radhika is suggesting something more informal.
> >
> > If we don't want to change the Author_List, meaning we want to keep the
> > official doc author as "Apache CloudStack," then we could add some
> language
> > to the abstract or some other intro text. Either an "Acknowledgments"
> > section, or just "We'd like to thank the following documentation
> > contributors for their help on version 4.0 of this documentation: ..." .
>
>
> You're right that the policy referred to doesn't apply in this case.
> Additionally, the @author tags are discouraged because it gives a sense of
> individual ownership of a part of a codebase, rather than the whole
> community. The same would apply if individual docs had author markup, but a
> general list of contributors is probably fine - if everyone wants to
> maintain it. The important thing is to be consistent - across the project,
> and over time. I don't know how the author group file renders to know
> whether that is an appropriate way to capture it, but if you want to go
> down this path you might be better off having a general thanks page for all
> of CloudStack, not a doc. specific one.
>
> - Brett
>
>
> --
> Brett Porter
> brett@apache.org
> http://brettporter.wordpress.com/
> http://au.linkedin.com/in/brettporter
> http://twitter.com/brettporter
>
>
>
>
>
>
--
NS
Re: [DOC] Updating Author List File
Posted by Brett Porter <br...@apache.org>.
On 10/10/2012, at 6:11 AM, Jessica Tomechak <je...@gmail.com> wrote:
>>> While I get the idea, isn't the documentation something that comes
>>> from the Apache Software Foundation? (Remember the CLA?)
>>>
>>> As a group we are contributing to the project as a group, the
>>> CloudStack brings out a new release, not the individual members.
>>>
>>> So I'm not sure that we should mention the individual contributors to
>>> the documentation, I don't think so.
>>>
>>> Wido
>>
>>
>> Exactly - we've already removed many names from source code and docs.
>> While we appreciate individuals work it does become unmaintainable over
>> time, and we are doing this as a community working together.
>> Radhika you do have a file named Author_Group - and you'll notice (unless
>> someone has recently changed things) that the author is "Apache CloudStack".
>>
>> If you need to track who contributed it, our revision control system has a
>> wonderful functionality called 'git blame' which is far more accurate than
>> an authors file will ever be.
>>
>> Plus there is a policy against this, see:
>> https://www.apache.org/dev/apply-license.html#contributor-copyright
>>
>> --David
>>
>
> David,
> It doesn't look to me as if that policy applies. We're not adding
> individual copyrights, just a "thank you for contributing" acknowledgment.
> I'm all in favor of the idea of giving doc contributors some public
> applause for their efforts. As Radhika said, it's mainly intended to
> encourage further contribution.
>
> I don't worry too much about the issue of maintaining an accurate
> Acknowledgments list in the future. Anyone who needs an exhaustive view of
> the contributors should look in the commit log, as others have noted.
> Radhika is suggesting something more informal.
>
> If we don't want to change the Author_List, meaning we want to keep the
> official doc author as "Apache CloudStack," then we could add some language
> to the abstract or some other intro text. Either an "Acknowledgments"
> section, or just "We'd like to thank the following documentation
> contributors for their help on version 4.0 of this documentation: ..." .
You're right that the policy referred to doesn't apply in this case. Additionally, the @author tags are discouraged because it gives a sense of individual ownership of a part of a codebase, rather than the whole community. The same would apply if individual docs had author markup, but a general list of contributors is probably fine - if everyone wants to maintain it. The important thing is to be consistent - across the project, and over time. I don't know how the author group file renders to know whether that is an appropriate way to capture it, but if you want to go down this path you might be better off having a general thanks page for all of CloudStack, not a doc. specific one.
- Brett
--
Brett Porter
brett@apache.org
http://brettporter.wordpress.com/
http://au.linkedin.com/in/brettporter
http://twitter.com/brettporter
Re: [DOC] Updating Author List File
Posted by Jessica Tomechak <je...@gmail.com>.
-----Original Message-----
> From: David Nalley [mailto:david@gnsa.us]
> Sent: Tuesday, October 09, 2012 8:32 AM
> To: cloudstack-dev@incubator.apache.org
> Subject: Re: [DOC] Updating Author List File
>
> On Tue, Oct 9, 2012 at 5:15 AM, Wido den Hollander <wi...@widodh.nl> wrote:
> > On 10/09/2012 08:13 AM, Radhika Puthiyetath wrote:
> >>
> >> Hello Community,
> >>
> >> We are in the process of updating the Author List for the ASFCS 4.0
> >> documentation.
> >>
> >> Request all the amazing documentation contributors to share their
> >> name and email id.
> >>
> >> As promised, your name will be displayed in the contributors list in
> >> the documentation.
> >>
> >> Thank you again for all your enthusiasm and hard work towards getting
> >> the documentation ready for ASFC 4.0.
> >>
> >
> > While I get the idea, isn't the documentation something that comes
> > from the Apache Software Foundation? (Remember the CLA?)
> >
> > As a group we are contributing to the project as a group, the
> > CloudStack brings out a new release, not the individual members.
> >
> > So I'm not sure that we should mention the individual contributors to
> > the documentation, I don't think so.
> >
> > Wido
>
>
> Exactly - we've already removed many names from source code and docs.
> While we appreciate individuals work it does become unmaintainable over
> time, and we are doing this as a community working together.
> Radhika you do have a file named Author_Group - and you'll notice (unless
> someone has recently changed things) that the author is "Apache CloudStack".
>
> If you need to track who contributed it, our revision control system has a
> wonderful functionality called 'git blame' which is far more accurate than
> an authors file will ever be.
>
> Plus there is a policy against this, see:
> https://www.apache.org/dev/apply-license.html#contributor-copyright
>
> --David
>
David,
It doesn't look to me as if that policy applies. We're not adding
individual copyrights, just a "thank you for contributing" acknowledgment.
I'm all in favor of the idea of giving doc contributors some public
applause for their efforts. As Radhika said, it's mainly intended to
encourage further contribution.
I don't worry too much about the issue of maintaining an accurate
Acknowledgments list in the future. Anyone who needs an exhaustive view of
the contributors should look in the commit log, as others have noted.
Radhika is suggesting something more informal.
If we don't want to change the Author_List, meaning we want to keep the
official doc author as "Apache CloudStack," then we could add some language
to the abstract or some other intro text. Either an "Acknowledgments"
section, or just "We'd like to thank the following documentation
contributors for their help on version 4.0 of this documentation: ..." .
Jessica T.
CloudStack Tech Pubs
Re: [DOC] Updating Author List File
Posted by David Nalley <da...@gnsa.us>.
On Tue, Oct 9, 2012 at 5:15 AM, Wido den Hollander <wi...@widodh.nl> wrote:
> On 10/09/2012 08:13 AM, Radhika Puthiyetath wrote:
>>
>> Hello Community,
>>
>> We are in the process of updating the Author List for the ASFCS 4.0
>> documentation.
>>
>> Request all the amazing documentation contributors to share their name and
>> email id.
>>
>> As promised, your name will be displayed in the contributors list in the
>> documentation.
>>
>> Thank you again for all your enthusiasm and hard work towards getting the
>> documentation ready for ASFC 4.0.
>>
>
> While I get the idea, isn't the documentation something that comes from the
> Apache Software Foundation? (Remember the CLA?)
>
> As a group we are contributing to the project as a group, the CloudStack
> brings out a new release, not the individual members.
>
> So I'm not sure that we should mention the individual contributors to the
> documentation, I don't think so.
>
> Wido
Exactly - we've already removed many names from source code and docs.
While we appreciate individuals work it does become unmaintainable
over time, and we are doing this as a community working together.
Radhika you do have a file named Author_Group - and you'll notice
(unless someone has recently changed things) that the author is
"Apache CloudStack".
If you need to track who contributed it, our revision control system
has a wonderful functionality called 'git blame' which is far more
accurate than an authors file will ever be.
Plus there is a policy against this, see:
https://www.apache.org/dev/apply-license.html#contributor-copyright
--David
Re: [DOC] Updating Author List File
Posted by Wido den Hollander <wi...@widodh.nl>.
On 10/09/2012 08:13 AM, Radhika Puthiyetath wrote:
> Hello Community,
>
> We are in the process of updating the Author List for the ASFCS 4.0 documentation.
>
> Request all the amazing documentation contributors to share their name and email id.
>
> As promised, your name will be displayed in the contributors list in the documentation.
>
> Thank you again for all your enthusiasm and hard work towards getting the documentation ready for ASFC 4.0.
>
While I get the idea, isn't the documentation something that comes from
the Apache Software Foundation? (Remember the CLA?)
As a group we are contributing to the project as a group, the CloudStack
brings out a new release, not the individual members.
So I'm not sure that we should mention the individual contributors to
the documentation, I don't think so.
Wido
> Thanks
> -Radhika
>
Re: [DOC] Updating Author List File
Posted by "Musayev, Ilya" <im...@webmd.net>.
I'm going to second that with Russian translation help if needed.
Feel free to reach out to me. Email imusayev@webmd.net
Thanks
Ilya
On Oct 9, 2012, at 3:00 AM, "路人甲" <me...@gmail.com> wrote:
> I'm willing to work on the documentation localization work for Chinese
> CloudStack enthusiasts.
> metalzhao metalzhao@gmail.com
>
> 2012/10/9 Radhika Puthiyetath <ra...@citrix.com>
>
>> Hello Community,
>>
>> We are in the process of updating the Author List for the ASFCS 4.0
>> documentation.
>>
>> Request all the amazing documentation contributors to share their name and
>> email id.
>>
>> As promised, your name will be displayed in the contributors list in the
>> documentation.
>>
>> Thank you again for all your enthusiasm and hard work towards getting the
>> documentation ready for ASFC 4.0.
>>
>> Thanks
>> -Radhika
>>
Re: [DOC] Updating Author List File
Posted by 路人甲 <me...@gmail.com>.
I'm willing to work on the documentation localization work for Chinese
CloudStack enthusiasts.
metalzhao metalzhao@gmail.com
2012/10/9 Radhika Puthiyetath <ra...@citrix.com>
> Hello Community,
>
> We are in the process of updating the Author List for the ASFCS 4.0
> documentation.
>
> Request all the amazing documentation contributors to share their name and
> email id.
>
> As promised, your name will be displayed in the contributors list in the
> documentation.
>
> Thank you again for all your enthusiasm and hard work towards getting the
> documentation ready for ASFC 4.0.
>
> Thanks
> -Radhika
>