cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [doc] policy for authorship credit
Date Mon, 01 Jul 2002 15:45:59 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.
> 
> 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?

*BIG* +1

I think you had a great idea. Maybe a visible location for changes is
*exactly* what is missing between the visibility of writing code and
writing docs.

Thanks for pointing this out.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------



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


Mime
View raw message