Re: Building prog first

[Reuben Thomas]

On 23 March 2010 17:15, Alfred M. Szmidt <address@hidden> wrote:
>
>   2010/3/22 Alfred M. Szmidt <address@hidden>:
>   > 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