[Zope3-dev] Re: Zope 3 Documentation and Quality Assurance

[Brad Bollenbach]

Le jeudi, 22 jan 2004, à 21:39 Canada/Eastern, Simon Michael a écrit :

> Oh, and I meant to say: a problem then is how to serve both people 
> writing/evolving the docs, and people looking for high-quality with a 
> certain level of polish, in the same wiki. With time the overall 
> quality will rise, but meanwhile we need to help people recognize the 
> status of each document and find the more polished/up-to-date ones if 
> that's what they need. Perhaps the IsDraft and similar badges help 
> here ?

Yes and no.

IsDraft should mean something more along the lines of a conceptual 
draft, not another way of saying "this document hasn't been 
spellchecked." The only excuse to ever find a spelling mistake in a 
document is when it's something a spellchecker doesn't catch (e.g. 
"too" instead of "two".)

FWIW, you'll note in the recent (long) thread regarding the new Use 
proposal, at least one person (other than myself) was confused by 
something that would have been caught by a basic spellcheck. Others 
still described the proposal as being too wordy and lacking enough 
concrete examples to clearly explain the point. In the end, nobody 
understood the proposal clearly except the authors that wrote it. A 
significant amount of effort was expended on the discussion of a 
document that nobody really understood.

This is something that a documentation QA team would help to address 
(because, as mentioned previously, having one or two technical editors 
would be a necessary component of any such team.)

The precedent here is, of course, Python itself. PEP's are often 
heavily "IsDraft" state. Despite that, I've never seen one that 
contained any (obvious) editing mistakes, and in the same vein I find 
myself revisiting PEP's from time to time to understand how a certain 
(relatively new) Python feature works, so I'm thankful that due 
attention is given to their readability when they're written.

Unfortunately, my proposal cannot work without the support of the 
people that are producing the documentation, in particular proposals 
and other development-related documents, which see the peak of their 
usage when they're first released. If trying to keep these high quality 
is always a game of catch-up -- instead of authors spending the extra 
time up-front to edit and having at least two or three reviewers to 
edit it before it's put up for the rest of the world to discuss or 
learn from -- the effort to edit and improve them will mostly be spent 
when the documents have already been read.

Is any time really being saved by "getting something up quickly" on the 
Wiki? Not from my point of view.

--
Brad Bollenbach
BBnet.ca