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 addressed. 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. --David > Subject: [docs] Draft RMI generator tutorial needs technical review > Date: Tue, 14 May 2002 08:29:12 -0400 > From: Diana Shannon <[EMAIL PROTECTED]> > > 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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
