[Zope3-dev] Zope 3 Documentation and Quality Assurance

[Brad Bollenbach]

Hi all,

I've been meaning to write something like this for a while, but have 
been put off for fear of sounding like a nitpick. I now realize that 
I'm not alone in my opinion on this, and that something really must be 
done. I've already discussed this issue with some members of the core 
development team on IRC, but I realize a post to the mailing list will 
reach a much wider audience.

The documents on the Zope 3 Wiki (i.e. proposals, vision statements, 
cookbooks, etc.) are in a relatively sad state with respect to editing. 
I read almost all the new proposals that are linked from the mailing 
list, and it's all too common to find them containing half a dozen to a 
dozen spelling errors each, which in the best case just makes them a 
bit more difficult to read, and in the worst case actually obscures the 
author's intent or causes the HTML that is output to break in some 
browsers, leaving half the document unrendered. (I can provide examples 
of each problem, if more concrete references are required.) In any 
case, IMHO, this can only reflect poorly to potential users of Zope 3.

The Pope himself has emphasized the focus on making Zope 3 really great 
software, rather than trying to push a production release ASAP, so the 
documentation that does get written (the proposals, the cookbook, and 
other related Zope 3 Wiki documents) *must* follow the same 
high-quality standard. To achieve a documentation standard that matches 
the coding standard, I propose the following:

1. For document writers, please give due concern to editing the content 
you write.

An extra 10-15 minutes spent to spellcheck, grammar check and format 
check (e.g. Should this be a bulleted list or a numbered list? Has the 
document in question been "chunked" into good paragraphs? Are there 
places where 15 words are used to explain what 5 could have done more 
clearly? Or vice versa? etc.) will make a much more pleasant experience 
for those who read your proposals, recipes, and thoughts on the future 
direction of Zope. All of these are documents that get referred to 
again and again (even if a proposal is only to remind core developers 
of why it ended up getting rejected. :)

2. The obvious one: document readers, please correct any obvious 
spelling, grammar, or formatting mistakes as soon as you spot them.

Please offer suggestions for ways in which you feel a concept could 
have been more clearly explained, because rest assured, you're probably 
not the only one who got confused. :)

3. Perhaps an official "Documentation QA Team."

Ideally this would consist of at least one or two technical editors as 
close to the core as possible, and one or two non-technical editors. 
Also, again ideally, the documents that will get posted to the Wiki 
would pass under the eyes of the editing/doc QA team before being 
published on the Wiki.

I'm a Python developer, but not currently active in Zope 3 core 
development itself, but I'm more than happy to do non-technical 
editing. I could even be the self-appointed leader of this editing 
team. I'd welcome emails from people reading the available 
documentation, even if just to say "Brad, I've noticed <some wiki 
document> contains quite a few mistakes, could you clean it up when you 
have a minute?" and just let me do the rest. This also means that if QA 
starts slipping on the documentation, I could officially accept the 
blame. :) And finally, it would mean that if you submit content to the 
Wiki without having it first edited, you'd probably *ahem* get an email 
from me. :)

When it comes to documentation, words are all we've got; please choose 
them carefully.

Comments and feedback, as always, are welcome.

Regards,

--
Brad Bollenbach
BBnet.ca