Re: Policy for /usr/doc/<pkg-name>-doc

[Raul Miller <rdm@test.legislate.com>]

Avery Pennarun <apenwarr@worldvisions.ca> wrote:
> Not a bad solution, but still the location of the docs won't be 100%
> obvious -- at first glance, I think I would expect /usr/doc/apache-doc
> to contain more docs than /usr/doc/apache. (Then again, that's just
> me.)

After thinking about it, I've decided that the proper solution doesn't
involve changing the mechanical layout of the documentation -- it
involves documentation.

If there was a consistently named readme file which had near the begining
a paragraph explaining where to find the various forms of documentation
[and, if that documentation is in another package, naming the other
package and indicating where the resulting docs would appear], that
would solve the immediate need.

[I should note that I've gotten into the habit of first looking at
/var/lib/dpkg/info/____*.list to see where binaries and doc files appear.]

It's tempting to attempt to regularize this approach so that automated
browsing tools could be smarter -- but I think it's important to recognize
that no matter what we do we'll have to re-do it later as we acquire a
better understanding of our needs.

For now what's most important is that it be simple to describe to a person
how to find the relevant docs, and that it be simple for that person to
find the docs.  We have to allow for some uncertainty and some randomness,
and so at the moment I'm leaning towards simple paragraphs of description.

-- 
Raul