On 23 March 2010 18:12, Alfred M. Szmidt <a...@gnu.org> 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