cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ivelin Ivanov" <ive...@apache.org>
Subject Re: [docs] opensource and quality control
Date Wed, 15 May 2002 13:50:23 GMT

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" <bdelacretaz@codeconsult.ch>
To: <cocoon-dev@xml.apache.org>
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:
>   cocoon-docs@xml.apache.org 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: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>


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


Mime
View raw message