making review/bug filing optional for some docs changes

[Shane H. W. Travis]

On Sun, 20 Mar 2005, Gervase Markham wrote:

> Shane H. W. Travis wrote:
> > To date, to the best of my knowledge, nothing has been done on that front;
> > No bugs filed, no patches uploaded, nothing.
>
> Nope. And, thinking about it, here's why. Doing the analysis to find out
> what needs fixing, and writing up some sort of proposal to explain it in
> detail, is simply an impossible task.

No one (as far as I'm aware) is requiring that you give more detail *in
advance* of working on a documentation reorg than you give when you work
on a major piece of code architecture. All that is being asked is that
you open a bug, and post your patch for review before it is committed to
the trunk. Amount of extra work: 2 minutes to make the bug, 2 minutes to
make the diff, two minutes to attach the diff.

Heck, even if you didn't want to do the work yourself, you could have still
opened the bugs;

http://bugzilla.org/cgi-bin/mj_wwwusr?user=&passw=&list=developers&brief=on&func=archive-get-part&extra=200501/110

You named three things there that are worthy of documentation bugs. I asked
you to open bugs against them so that they could be addressed -- if not by
you, then by someone else. You already know the general outline of the
issues you addressed there, or else you couldn't even have brought them up.
Nobody asked for a road map or a highly detailed analysis... just an
infodump on why you think it needs doing and maybe even one way to approach
it. Is even that too much to ask?


> Now, that section was, as a whole, absolutely definitely much, much
> better after I'd finished than before I started (if you disagree with
> that, shout - but I really don't expect anyone to).

Fine, here's my shout. I like the 2.16 step-by-step Installation
Instructions far better than what is currently in 2.18 or 2.20.  They're
easier for a rank beginner to understand, in that they provide a 'do this,
then do this, then do this' format that can be easily followed. For more
experienced people it's easier to find information about specific things on
MySQL (for example) when the information is all are in one section, rather
than split between Installation and Configuration. I often go back to the
2.16 docs rather than use the 2.18 ones, because I find it far more
difficult to find what I need in the 2.18 docs. At some point, when I've got
the time, I'd like to open a bug to re-write things and bring back the
step-by-step process.

Since you asked.

Does that mean that nothing you did needed doing? Of course not. You fixed
up a lot of stuff that needed fixing; I just didn't like the shape of the
end result. Since it's already done, though, what's the point in discussing
it *now*?


> But before I started, could I have defined what I was going to do? Not
> except in terms so vague as to be useless.

I would assert that the whole process could have benefitted from some more
structured goals; if you're not even sure what your endpoint is, how do you
know if you're there yet?

Bugs with one goal -- even when that goal is a huge one, like "update the
entire FAQ" or "Add a troubleshooting guide" or "Amalgamate the windows
documentation found everywhere into one location"  provide a solid surface.
They give guidance by which others can assess if one is doing it right or
not, or if there are places where things have been missed/need inclusion. I
assert that this is a good thing, and beneficial for the docs as a whole.


> Once I'd finished, a couple of bugs got filed - "you changed this, and
> we don't like it". Cool - no problem. Let's change it back. That doesn't
> mean the entire procedure was broken, just as if you check in a code
> patch and it causes regressions, it doesn't mean the patch was a bad idea.

That code patch in your example had many people look at it to determine if
it was a bad idea before it ever gets done. First of all, it's subject to
general analysis on creation, then someone has to review it, then someone
else has to approve it. Only then does it get checked in.

As I understand it, the result of your 16 hour docs hackathon ended up with
people being presented with a 'fait accompli'. Nobody even got a chance to
say if they thought it was a good idea or not; you did it, and you checked
it in. Voila!

Note, however, that when you asked what people thought about doing the same
thing for 2.18, the answer was a resounding 'no'.

(Being willing to change things back does not make it any less of a 'fait
accompli'. It was done, it was checked in, and nobody got to look at it
BEFORE that happened is the point I'm raising.)

In UI design, there are some big names in the field who say that 'computer
mockups' -- even if there is absolutely no functional code behind them --
are a bad way to get user feedback on designs. The user will see the screen
and be less willing to make suggestions because zie will be inherently
unwilling to discard the effort already put forth to get the design to this
point. Presented with the exact same design in a pencil-and-paper sketch,
however, people are much more willing to suggest improvements, as they know
that the effort required to get to this stage is orders of magnitude less. I
submit that you ran into a similar case; people appreciated the work you
HAD done, and didn't really want to undo/invalidate that work even if they
thought that parts of it shouldn't have been done like that.

> Now, I'm not expecting to be allowed to do such a major change the day
> before a release.

Then you've changed your expectations in the last two months.

http://bugzilla.org/cgi-bin/mj_wwwusr?user=&passw=&list=developers&brief=on&func=archive-get-part&extra=200501/100

Factual note: it is actually *two* days before the 2.18 release that you
wrote this, asking for carte blanche to re-write the docs as you saw fit. As
such, you could probably claim victory on a technicality.



This letter got more into the personal/historical and less into the
meta-topic, but my belief is that documentation can benefit from design just
as much -- if, perhaps, in different ways -- as code can. When Bugzilla
started off, based on what I've seen/heard, there was little-to-no attempt
at uniformity of style, or code integration, or code reuse... people just
added things as they thought it needed adding. Now, despite there being a
lot more people adding to the whole, there is a real effort to make things
consistent, documented, and well-formed.

It may be true that docs aren't in very good shape right now; one could
easily compare them to the state of the code four or five years ago (which I
recall reading someone describe as 'an abominable mess'). The code hasn't
gotten prettier/better because we *relaxed* the restrictions on it, though,
and just let people check in things whenever/wherever they wanted to... and
I don't think going down that route would help the docs much either.

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