At 08:33 AM 01/07/2002 -0400, you wrote: >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.
+1 It took me a week to figure out how XMLForms worked and to write up the doc as I'm new to Java being a PHP programmer. I think it is fair to be credited for what you have done. >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 +1 I like this too! Everyone who contributes should get a credit. Heidi >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] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
