Re: Building prog first

[Reuben Thomas]

On 23 March 2010 18:12, Alfred M. Szmidt <address@hidden> wrote:
> You say that the manuals are poor

I said that the indices are poor, specifically at indexing concepts
rather than just keywords, function names &c., in general. I also said
that the manuals in general are excellent.

> and that it is obvious, but I cannot
> figure out from your explanation how they are poor.  I've looked at a
> few manuals, glibc, emacs, coreutils, autoconf, and m4, and all of
> them have good indices, are organised cleanly, etc.

To understand what I mean by a good index, have a look at a book on
indexing, or for a more personal take, along with an exemplar, Douglas
Hofstadter's "Gödel, Escher, Bach".

> Can you mention one or two manuals, and which part of those manuals
> you find to be inadequate?

The parts I find inadequate are the indices (as I have said repeatedly).

I have already cited the indices of the autotools manuals, e.g. those
of the autoconf and automake manuals. I've just had another look at
them: they have lists of functions, environment variables &c. and each
has a general or "concept" index, which lists the above, plus, as far
as I can see, a mixture of section headings and the sort of entries
that one might put into a glossary, and not the sort of headings that
bring out the structure of the subject of the manuals. I also
mentioned Emacs's manual, but I see on further investigation that it
doesn't (at least in my version, 23.1, have an index).

> You mention that web access improves the manuals, how do they do that
> exactly?

They take me to answers to specific questions.

>  If you do a web search, then you will invariable end up at
> the manual, no?

No, normally I end up on a web page or in a mailing list message.

> If our manuals are not read and users think that reporting bugs,
> improving them, is a waste of our time, then it would be better that
> we remove them, since keeping them updated takes alot of time, more so
> than actually improving our programs.  But users clearly need manuals,
> as from your experience, and a bad manual is just as much a bug as
> anything else in our programs.

I think we're in furious agreement here.

> Please don't think that improving a manual is any less of an
> improvment than adding a very useful feature.

And again!

-- 
http://rrt.sc3d.org