cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <>
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):
> 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.
<>                             Friedrich Nietzsche

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

View raw message