cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Heidi Brannan <>
Subject Re: [doc] policy for authorship credit
Date Mon, 01 Jul 2002 21:48:56 GMT
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):

+1 I like this too! Everyone who contributes should get a credit.


>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:
>For additional commands, email:

To unsubscribe, e-mail:
For additional commands, email:

View raw message