Documentation for the release

[Jake]

Gervase Markham wrote:

> Well, then we are completely doomed :-|

This is a bit dramatic, don't you think?

> Seriously, you wouldn't have to review it all - people could review 
> different bits. We could share it out.

An act which is made much easier by submitting small and more focused 
patches. This is especially true where new features are concerned as you 
can ask not only a docs reviewer to look at it, but also somebody who's 
familiar with how the feature works.

> The problem I find with docs is that if you approach it like code, in 
> a "patching", you just work really slowly. The fact that we store the 
> docs as XML shouldn't fool us. What other authoring group uses a 
> "patching" approach to writing prose? People edit, and re-edit as they 
> pass over and re-read the document. That's the only way you get 
> something that's coherent, consistent and flowing.
>
Yes, we are writing something kind of like prose, but at the same time 
we're not writing a novel, we're we're writing a technical manual. But 
even in the novel example, if you find an error in chapter 13, you don't 
have to rewrite chapter 27 nor does the editor have to reread (review) 
chapter 27. True, one there's a final version (rc), the book should be 
read in its entirety to make sure that it makes sense. But truthfully, 
we're a long way away from a final version of the Bugzilla Guide. At 
this point I'm much more concerned with technical accuracy followed by 
spelling and basic grammar. Things like smooth flow throughout the 
entire manual and overall first/third person agreement may be nice, but 
they are a much lower priority.

> Gerv
> -
> To view or change your list settings, click here:
> <http://bugzilla.org/cgi-bin/mj_wwwusr?user=jake@bugzilla.org>