Documentation for the release

[Shane H. W. Travis]

On Sat, 15 Jan 2005, Gervase Markham wrote:

> Jake wrote:
> > Gerv wrote:
> > > 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.

Agreed.


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

It's just as much bother for code too... yet somehow code still keeps
getting written. Why?
- writing new features is *way* more fun than writing new documentation
- people are much more confident in their ability to write good code than
	they are in their ability to write a good sentence

This is a generalization, of course, but I think it's a pretty fair
generalization. Even for myself -- and, from discussion with him, even for
Jake -- we both like doing new features and stuff as much as (if not more
than) doing docs... but we do it because we're capable of it, and it needs
doing.

One other reason that (IMHO) documentation lags is SGML formatting. Sure,
it's not difficult, but it's one more hurdle for the person who doesn't do
it often. What I'd like to see is a new procedure change, that when one
writes a Bugzilla enhancement, it will not be checked into the trunk until
there also exists a .txt file that explains how the enhancement works, what
it affects, and what it does. This would NOT have to be in polished prose or
proper SGML... but it would have to exist. That way the documentation team
at least has a starting point when they go to write up the docs.


> Docs aren't like code - you can't "break" them... This means you can take
> a much more free attitude to changing them than you can to code.

You are, of course, entitled to your opinion. Dave, myself, and now Jake
have all indicated that we disagree/are not comfortable with the 'do it all
at once in a paroxysm of verbiage' approach.


> 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 would agree with you... if the only thing that was ever being done was
patches to add specific bits of information, or fix specific issues and
mistakes. Fortunately, that's not how it has been working in my (admittedly
short) experience.

Not all patches are of the same magnitude. Some are small ('link is
incorrect'), some are moderate ('need some more examples of how groups
permissions work'), and some are large ('Need docs on flags', 'windows docs
needs to be brought up-to-date'). Some of them are meta-issues ('FAQ
Overhaul', 'Integrate hacking FAQs and Developers Guides') that deal with
the documentation as a whole, rather than specific bits of information
contained therein.


> When I talk about a massive hackathon, ... 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...

There is no overwhelming reason that any of these items you mention *must*
be done as part of an all-or-nothing approach; they're all perfectly suited
to being done as individual tasks. I would welcome bugs being opened on any
or all of these things. (I would welcome it even more if, after opening the
bugs, you took on the task of getting them done... :)

On a more general topic, I've been trying to get people to open more docs
bugs if they see something that's wrong, or can't find some information that
they're looking for, or find it in five different places and think it should
be amalgamated into one. I'd love it if people could get into the habit of
doing this, in the same way that they open bugs against Bugzilla if they see
something that doesn't work there. If information is missing from the docs,
don't assume that the doc-writers know about it.


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

Then I assert that the time to ask the question about what shape the docs
are in would have been three months ago... not 48 hours before a planned
release, stating that "we are completely doomed" unless we let you do it
your way.


Fortunately, one way in which 'docs are not like code' (at least so far as
Bugzilla itself is concerned) is that code is only released at specific,
discrete intervals. The Bugzilla docs are updated www.bugzilla.org (which is
where I'd bet that >95% of English-speaking people come looking for
documentation) happen every fifteen minutes. When something gets checked in
to the docs, it is almost instantaneously available to the public at large.
This means that we do not have to make it through a specific window before
it closes on us.


Just for the record... I'm not *opposed* to the idea of large-scale
rewrites; I've already done one or two myself. I do think that trying to
do the whole docs at once when there are already >70 documentation issues
outstanding is not reasonable, however. Once things are caught up and the
bugs that we KNOW to exist have been addressed, I would be much more
receptive to the idea.

In the mean time, please post bugs on the issues you raise above, and feel
free to help reduce the time until that date by attacking the existing
documentation bugs.

Shane H.W. Travis       | The greatest of all mistakes is to do nothing
travis at sedsystems.ca    |  because you can only do a little.
Saskatoon, Saskatchewan |   Do what you can.  -- Sydney Smith