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