Documentation for the release

[Jake]

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

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.