cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject [docs] opensource and quality control
Date Wed, 15 May 2002 05:45:04 GMT
The issue of how to introduce at least some minimal
quality control for documentation is creating some friction
on this list. Let us nip it in the bud before it blossoms.

Opensource is all about getting something done and
getting it out so that everyone can build upon it. By the
very nature of opensource, issues will eventually be

However, with documentation it is easy to kill a project
if confusing and misguided documents are allowed to
be published.

So, let us develop a procedure whereby the opensource
model is still employed, yet there is initial quality control.

I think that we already have this. It is the duty of the
committer to undertake initial quality control when they
accept the patch from Bugzilla and prepare for their commit.
If they do not know anything about the topic, then they
should not be taking on the patch - let someone else do it.

There will certainly be occasions where a single committer
does not have the expertise to do a review. For these cases
we should have a Draft documentation directory under the
normal src/documentation/xdocs/ (... we already have a
drafts/ directory but it is not linked in). However, for this
to work, we would need to have the website updated far
more often than what currently happens.

After the initial commit, then a notice should be sent to
cocoon-dev to give a chance for review before release.
If there are no comments or fixes, then too bad - it all just
gets released with the authors fixme notes embedded.

The other alternative is to try to set up an area in the
CVS scratchpad to hold any documents with obvious
problems. However, it seems hard to configure the build
procedures for the scratchpad so that "build docs" can
prepare them too. There is a tendency for stuff to languish
in the scratchpad and never see light, so we would
probably just have a different issue. Also, the scratchpad
docs would not get published to the website, so no
opportunity for review by a wider audience.


> Subject: [docs] Draft RMI generator tutorial needs technical review
> Date: Tue, 14 May 2002 08:29:12 -0400
> From: Diana Shannon <>
> Stefano Mazzocchi wrote:
> > Ah, one suggestion: don't wait too much for comments.
> > People don't tend to comment *before* things are placed
> > live on the web, but *after*.
> What do you mean: that developers are more motivated to fix 
> documentation errors once they are public? Or, that advanced,
> motivated users will catch and help fix these problems eventually?
> So what do you suggest we do when an author clearly has
> a question or hole? Should that author post a question to
> cocoon-dev, asking for help?
> I'm all for "lowering the bar," but why allow new docs to
> create additional confusion for users when we have the
> talent to eliminate *some* of this up front.
> Remember, it's not code. It doesn't break. New 
> and less advanced users give up and go learn Zope...
> Diana

To unsubscribe, e-mail:
For additional commands, email:

View raw message