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.
<[EMAIL PROTECTED]> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
