On 23 March 2010 17:15, Alfred M. Szmidt <a...@gnu.org> wrote: > > 2010/3/22 Alfred M. Szmidt <a...@gnu.org>: > > If searching is the problem > > *Web* searching is the answer, not the problem. > > It isn't when you are not connected to a network.
I usually wait until I am; it often takes me rather longer to answer questions by simply reading the manuals. > I rarely find anything useful in the indices other than particular > functions or variables. Rarely, in GNU manuals, concepts, but that is > because they do not, on the whole, have good general indices. > > Do you have a list of such manuals? No, but it's most of the manuals I've looked at. > Would you like to report this to the relevant maintainers? No, for several reasons: 1. It's fairly obvious that the indices are in general poor (in common, I should add, with those of most books ever printed). 2. Such a general feature request (it's not really a bug report) is not the sort of thing I usually find useful as a maintainer. It's more useful to notice that I see the matter discussed several times. 3. In practice, I'm really not sure that it's the best use of maintainers' time: as I say, I can generally solve these problems by doing web searches, or if not, then posting a question to a mailing list which hopefully generates a good answer that then becomes searchable. I think spreading internet access to those who don't have it is a much more important goal than writing manuals that answer every question, and further, having better indices would only help slightly. > One cannot improve what one does not know about. True. But this problem is an endemic one, so efforts like Project Mallard, which aims to improve all GNOME programs, at least, are more useful than bug reports to specific projects. > Would youlike to suggest a better structuring for some manuals? No: as I've already indicated, I simply don't know enough. In particular: 1. I don't know how to improve the structuring of manuals to answer these questions better. 2. It's unclear to me that changing the structure of manuals would help much. 3. It is almost certain that changing the structure of manuals would make them less useful for other sorts of use, for example, for users wishing to learn about a system comprehensively, or those who wish for a technical reference. In conclusion: a. With web search, this problem is not so bad currently. b. To improve the way documentation is written will require a great deal of research and experimentation. While individual GNU maintainers who feel strongly about that may wish to do this for their particular packages, it seems unwise to me to encourage all maintainers to do "it" when it is unclear what "it" is. Until there is a sense of emerging consensus and best practice, sticking with the status quo seems far better to me: GNU manuals are frequently high quality manuals of what one might call the "classic" kind, and by imitating the best of them one will do far better than by trying to guess what something better but different might be like. It is possible that I gave the wrong impression either about how serious the problem is (even for those without internet access, careful reading and searching of an Info manual will usually find one the answer eventually), and/or that I gave the impression that I know how to fix the problem (I have only the vaguest idea). I'm sorry in either/both cases. -- http://rrt.sc3d.org