Documentation for the release

[Gervase Markham]

Jake wrote:
> An act which is made much easier by submitting small and more focused 
> patches. 

IMO, the reason documentation falls behind code is the requirement to 
submit small and focussed patches for every change. It's much more 
effort this way, and people just don't bother.

Docs aren't like code - you can't "break" them, thereby making the whole 
document useless. (Yes, I know about SGML well-formedness. That's not 
what I meant.) Problems are localised to a particular mistake, and there 
are no weird side-effects. This means you can take a much more free 
attitude to changing them than you can to code.

If you take the patch approach to docs, the document slowly but surely 
becomes incoherent and inconsistent, because no-one takes an overall 
view and edits the entire manuscript to bring it back to a good and 
consistent state. I suggest that if you want good docs, this process, 
which is only really feasible in a "do it and then review it all" way, 
needs to happen at least once before every release.

Granted, it should probably happen a bit earlier in the process than now :-)

>> 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. 

Unless the bit you change in chapter 13 actually is supposed to go in 
chapter 27. This doesn't happen in a novel, but it does happen in 
technical documentation. I agree, technical docs are not like a novel - 
they undergo a vastly greater degree of change and rearrangement during 
editing.

> 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. 

Well, Dave's in the middle of releasing 2.18, so it seems a bit late now :-(

> 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.

When I talk about a massive hackathon, that's not the stuff I mean. I 
mean (hypothetically) reorganising all the installation instructions, 
adding three new administration sections, trimming the FAQ drastically 
and moving half the content to various places within the manual, 
re-editing to incorporate that text in a nice way... Major changes, in 
other words, in line with the assertion (made earlier) that "the docs 
aren't even close to where we want them to be" (or whatever he said).

The last time I did this, I must have made ten or twenty editing passes 
over the document, changing unrelated things each time as I massaged it 
into shape. If every pass had to be at least one and possibly more 
reviewed patches, it would have taken three months rather than a weekend.

Gerv