cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Noels <stev...@outerthought.org>
Subject Re: [doc] policy for authorship credit
Date Mon, 01 Jul 2002 12:44:19 GMT
Diana Shannon 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 (after having spent 1.5 days authoring the little primer mentioned 
underneath - I'm a slow writer)

> 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

please bear in mind that this has been done manually, and for exact the 
same reasons as you are mentioning: Ross had been doing _considerable_ 
editing and rephrasing on that document.

> 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?
> 

+1

We could add some (non-required) CMS revision elements/attrs to the 
document>header element and generate the revision history automatically 
at the bottom of the page. An idea for Forrest, perhaps?

</Steven

-- 
Steven Noels                            http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
stevenn@outerthought.org                      stevenn@apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message