Documentation for the release
jake at bugzilla.org
Sat Jan 15 09:54:37 UTC 2005
Gervase Markham wrote:
> David Miller wrote:
>> Quite frankly, that makes me a bit nervous. I'm still remembering a
>> major docs checkin about a year ago or so that went something along
>> the lines of "hey guys, I just checked in a major revision to the
>> documentation", which none of us knew was coming, and nobody had time
>> to go back and audit.
> So would anyone have had time to review it if I'd done it as a patch,
> then? :-)
If it were a patch per issue, it should be possible for people to find
time to review it. Unfortunately, I'm in a huge period of flux right now
so the chances of me doing many reviews are quite low. I know it can be
a bit of a pain, but it really is easier to review the charting portion
of the docs separate from, say, random changes in the FAQ.
>> At the time I just said "oh, I trust Gerv, we'll just hope it was
>> good" and then over the following months, it turned out important
>> things disappeared,
> I was never made aware of such problems. Would that not have been a
> sensible thing to do? No one gets better if they are unaware of their
A good place to look would be documentation changes that were made since
your massive checkin. A couple in particular that had to be undone was
the massive gutting of the Credits section and the removal of the
security section (which should have been, and now is, a chapter).
>> 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.
In existence? No, not once has anybody asked you to update 2.14, which
does technically still exist. However, all supported version should be
updated where appropriate. Obviously the new whining system doesn't have
to be documented in the 2.18 or 2.16 versions of the guide, but docs on,
say, the flag system certainly should be.
>> I'd very much prefer patches to each of the docs bugs for the
>> specific things they cover (some of those bugs are for reorganization
>> type changes, if I recall correctly, so some of them are ripe for
>> larger-sized patches).
> 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.
If documentation were a one person effort, I may agree. However, there
are many people who do (at least some) work on the docs. As such, one
should keep their work focused as much as possible and attempt to let
others know what they are working on. The best and easiest way to do
this is to simply use the tool for which the documentation is being
written: Bugzilla. When you have a bug ASSIGNED to you, it lets others
know that you are working on it. It also allows the others to ascertain,
to some extent, what parts of the guide you're likely to change.
> Having said that, I'm quite happy for there to be more warning, review
> and oversight :-) 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?
As I mentioned above, I personally, can make no such promise. I wish I
could, but to be honest, I'm not even sure that weekends still exist.
Another advantage of the multiple small(er) patch approach is that one
person doesn't have to carve enough time to review everything. Many
people can review much smaller portions.
I know this can be more of a pain for the person writing the patches as
instead of simply doing one huge update in place, you now have to juggle
a bunch of patch files, but I think we've certainly learned in the
codebase that one huge patch that fixes everything ends up being a waste
of time because nobody has the chance to review it.
More information about the developers