On 10/10/2012, at 6:11 AM, Jessica Tomechak <[email protected]> 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 [email protected] http://brettporter.wordpress.com/ http://au.linkedin.com/in/brettporter http://twitter.com/brettporter
