cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject Re: [docs] opensource and quality control
Date Wed, 15 May 2002 10:13:19 GMT

Bertrand Delacretaz wrote:

> 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.

I agree with Betrand. I'm starting to appreciate the need to use the 
wider community more loosely for CMS roles, not rely on a small group of 
overworked committers to provide all QA, even subject matter expertise. 
I agree, that if docs are marked draft, etc. we should be able to 
release them to the community for comments with the appropriate "use at 
your own risk" type disclaimers. I would really be sad if authors spent 
a lot of time and effort on a doc was never released because no 
committer had the time. I also really hope subject matter experts within 
the community would be able to provide feedback on documents as they are 
released in this "draft" form. It's a risk, though, if this doesn't 
occur.

> As opposed to code, docs are not easily declared "right" or "wrong", 
> they can
> start "usable" and become "great" over time I think.
I hope this is possible. This would be wonderful.

> 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.
I have something like this but a bit more elaborate based on the 
research I've done on CMS needs.

> b) each doc has a unique ID
Do we really need unique ID attribute if filename is unique, or is this 
short-sighted? I know this unique id is used with many database-driven 
CMS systems, but I'm questioning if we need this for Cocoon which gives 
us so many flexible matching options for requests?

> 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

Yes! Absolutely. I was planning to add this info at the transformation 
stage, especially given the new reality that author contributions may 
not be reviewed by cocoon-dev. Perhaps once we agree on dtds, you could 
implement this.

> (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.

I understand this discussion should occur on Forrest. Are you subscribed 
there? I'll post my current dtds there later today. Feel free to comment 
on/expand/revise them. I'm still struggling with how much CMS info 
belongs in primarily content docs, how much should remain separate.

Thanks.

Diana


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


Mime
View raw message