I need your input on how to think about bylines Cocoon docs, both community-contributed and core docs (soon to be patched by new volunteers).
I'm struggling to understand how to credit the efforts of people who make the docs better. This effort doesn't always equate to authorship, that is, you can spend hours editing a doc (I have) but not necessarily contribute a substantial amount of new content. Still, the doc is better as a result of your effort. I also want to avoid problems down the road when users patch docs and add their name as an author, even when they may have only contributed a single sentence. In other words, I want to reward bylines to people who take the first step of authoring a new doc or who add substantial amounts of additional content. Writing is hard. Patching (what someone else started) is often a lot easier. Example: lots of patches were submitted for XMLForm How-To. No patches yet for new How-Tos. Forrest introduces a revision content section. I like it. For an example, check out this document and look at the revision history section (at the bottom of the page): http://xml.apache.org/forrest/primer.html I think crediting individuals (committers as well as volunteers) for their patches in a Revision History section -- and not necessarily in the byline area, unless they are a co-author or add significant amounts of new content -- is the best way. It also serves as a meaningful record for users about updates to docs (i.e. how many users check cvs log info?). Some users have the mistaken understanding that core docs aren't being updated. This would demonstrate to them clearly what is going on. It would also visibly reveal documents which may need to be updated. I experimented with this approach in the How-To I created for the Paginator Transformer. I didn't write it originally, Stefano did on this list, so I gave him credit in the byline. However, I put a lot of time editing, restructuring, testing, debugging, adding samples, etc. so I noted my work in the revision section. Stefano has since updated the samples, so I will add another item to the revision section, noting his work. When users start reading the How-To, perhaps they will begin to appreciate the effort that goes into creating a good doc... Although I really don't like bylines at all in this context, especially for core docs, I think we need to keep them as an incentive for new authors to contribute docs (i.e. get "rewarded" with some visibility for their effort). It also gives them the incentive to maintain their contribution, because their name is publicly associated with the work. What do you think? -- Diana --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
