I second Bertrand. Iterative documentation works for other Apache projects as well. As long as there are inline notes asking for improvement, the doc will eventually improve.
----- Original Message ----- From: "Bertrand Delacretaz" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Wednesday, May 15, 2002 1:55 AM Subject: Re: [docs] opensource and quality control > On Wednesday 15 May 2002 07:45, David Crossley wrote: > >. . . > > So, let us develop a procedure whereby the opensource > > model is still employed, yet there is initial quality control. > >. . . > > Following the opensource model, I think docs should be released as early as > possible, with only minimal initial quality control but clearly flagged as > "draft" or something. AND it must be very easy for all readers to give their > feedback on the docs so that they can be improved. > > As opposed to code, docs are not easily declared "right" or "wrong", they can > start "usable" and become "great" over time I think. > > Ideally readers should be able to add their comment directly on the docs > pages, but as this is not possible today here I suggest the following > mechanism, which would be easy to implement: > > a) each doc has a status attribute: draft, reviewed, reliable, etc. > > b) each doc has a unique ID > > c) something like this published at the top of each document (auto-generated > from the "status" and "doc-id" attributes) > > document status: > draft > document id: > 12.452 > confidence level: > this information has not been verified yet, please comment if you find > mistakes in it > send comments/corrections about this document to: > [EMAIL PROTECTED] with "[doc-comments:12.452]" in subject line > > (include a "mailto" link for this and a link to a page that explains the docs > feedback process) > > Provided this is compatible with the current plan for the docs publishing > mechanism, I'd be willing to implement the necessary changes. > > -Bertrand > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, email: [EMAIL PROTECTED] > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
