Re: not all doc "clean-ups" are good

[Graham Percival]

On Fri, Aug 19, 2011 at 07:32:20AM +0200, Werner LEMBERG wrote:
> 
> > I'm also not convinced that the "insert breakpoints after slashes"
> > is a great change.  This makes the documentation source look
> > really cludgy; is there no way that the breakpoints could be
> > specified automatically?
> 
> No, there isn't.

Hmm.  The next question would be "how important is it to avoid (or
permit?  I've lost track of what we're doing here) line-breaks for
slashes" ?  I'm not certain that it's worth fiddling with this.

I mean, if I were writing any docs these days, I would not
personally bother with the /@/ format.  With that in mind, I can't
find it in myself to reject other doc-patches for not using /@/.
If that's the case, then is it really a step forward to half
inconsistent doc source in this respect?  That would confuse
inexperienced (i.e. less than 2 years) doc editors.

> Actually, slashes should be completely avoided within normal prose,
...
> Maybe there is a native speaker who could remove many of the
> `/@/' stuff by reformulating the affected phrases if possible?

Hmm.  I agree for the more formal "technical reference" sections,
but I would prefer to leave them in the "chattier" Learning
manual.

> In my opinion, the primary goal is to produce excellent documentation
> in the *target output*, right?  This means that the resulting PDF and
> HTML should be excellent, and we should do everything to reach this
> goal.  To do so, I accept some cludginess in the documentation...

I don't accept this as a general principle.  What if we could
produce excellent-looking documentation by moving to raw tex?  Our
pool of possible doc editors would instantly shrink by 90%; I do
not think that is a good plan for long-term *maintained*
documentation.

I think it's already a bit too hard to get involved in doc work.
I mean, just look at James!  He's spent almost two years learning
this stuff, but he still doesn't feel terribly confident.  Yes,
his background is windows rather than linux -- but approximately
half of our new developers in the past 4 years come from that
background.


Our docs are stagnating badly.  I've been hoping to have the Grand
Documentation Project 2 in the "near future", but at the moment it
looks like it's a choice of GLISS vs. GDP 2.  There's just too
many emergencies that keep on cropping up.  :(

Cheers,
- Graham