Documentation for the release
jake at bugzilla.org
Sat Jan 15 10:09:18 UTC 2005
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.
> To view or change your list settings, click here:
More information about the developers