Documentation for the release

[Shane H. W. Travis]

On Thu, 13 Jan 2005, Gervase Markham wrote:

> > and all of those changes that were also
> > applicable to 2.16 never got backported to the 2.16 docs.
>
> That's different. I don't think fixing the 2.18 docs obligates one to
> fix all versions of the docs in existence.

I agree that docs for versions we no longer support don't have to be kept
current, but IMHO all documentation for supported versions should be fixed
simultaneously.

The places they should differ are;
- Feature is new to a newer version
- Feature was changed from an older version to a newer version
- Feature was phased out after an older version

Other than that... my feeling is that they should be pretty much identical.
It sure makes patching (and diffs, for those who want to see what has
changed) a whole lot easier.

(Those are just my thoughts; Dave and Jake get the final say.)


> > I'd very much prefer patches to each of the docs bugs for the specific
> > things they cover
>
> I assert that if the documentation's in the state you say, without a
> 12-hour hackathon style thing, it's not going to be ready.

You may be right; in fact, I'll bet your right.

Despite that, my personal preference is that I'd rather not have it done
that way.


> If I promise to carve out my weekend for this, can others promise to read
> the result and perhaps compare it with the previous version to see if I've
> accidentally nuked important information?

So on top of your herculean hackathon, there would need to be a herculean
reviewathon too... which I don't have time for, and which would delay
release even further. I just cannot think of a time when I'll be able to sit
down and r= the whole bugzilla documentation manual at once.

(If you were talking about just checking it all in when you were done, and
having it reviewed in retrospect... then I'm even less copacetic with the
idea. Things benefit from having more than one pair of eyes look at it
before it becomes a fait accompli.)

There's lots of specific patches to attack. As I said, I'm planning to get
to as many as I can in the near future, but I'd welcome some help. All I ask
is that you assign it to yourself if you're going to do it (so that there
isn't a duplication of effort) and don't check anything in until it's been
reviewed... same as anywhere else in Bugzilla.

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