Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
Reply-To: cocoon-dev@xml.apache.org
Date: Mon, 1 Jul 2002 08:33:42 -0400
Mime-Version: 1.0 (Apple Message framework v472)
Content-Type: text/plain; charset=US-ASCII; format=flowed
Subject: [doc] policy for authorship credit
From: Diana Shannon <shannon@apache.org>
To: cocoon-dev@xml.apache.org
Content-Transfer-Encoding: 7bit
Message-Id: <C725D964-8CEE-11D6-A4CA-0030653FE818@apache.org>

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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org