PROPOSAL: complete list of documentation files, "man <packagename>", all man pages refer to said doc list in "See Also" section

[Jim Lynch <jim@laney.edu>]

Hi Mike and Kirrily:

Mike, if it's hard for you to imagine a more easy structure, I sorta tend
to agree, but note that the structure is not complete.

Kirrily, you had trouble finding docs that should have been apparent
immediately, and that is also due to the structure of the docs being
incomplete.

I THEREFORE PROPOSE: 

(1) each package should list the fully qualified path to every documentation
    file it installs. This list would be kept in /usr/share/doc/<packagename>.

(2) each package should install a man page in some section (I dunno which
    one, but sect 1 is probably not a good idea) named such that one can
    type "man <packagename>" or "man <theSect> <packagename>". 

    The job of this man page is to introduce the package, enumerate its 
    executables, refer to its special dirs (if any), refer to the 
    documentation directory /usr/share/doc/<packagename> and the list of 
    doc files (as in (1)) and give a heads-up if there is anything special
    about the package (maybe it has a /etc/init.d/<packagename> file).

(3) every file documenting the package should refer to the list of docs
    (as in (1) above) in a "see also" section.

(4) Some packages are documented in material not installed with the package.
    If the package maintainer is aware of such material (as (s)he would be
    if said outside docs were used in installing or configuring the package),
    then the maintainer would have two choices:

    (a) the package could be altered to include the material; or
    (b) the documentation list (as in (1)) could be altered to refer
        to the material, either by URL or other absolute pointer,
        such as an ISBN number for a book.

The list of documentation files for the package would act as a
clearinghouse for sources of info about the package. Because all docs
would refer to it, no one would be at a loss when trying to find the
docs to read. I know that complaints about not being able to find docs
prevail, even from maintainers.

I have heard many say "It's easy already" but when maintainers say "where
are the docs??", that goes far towards disproving the "It's easy" argument.
Yes, I know /usr/share/doc/<packagename> exists. But most of them contain
little better than a (required by policy) copyright notice.

-Jim

---
Jim Lynch       Finger for pgp key
as Laney College CIS admin:  jim@laney.edu   http://www.laney.edu/~jim/
as Debian developer:         jwl@debian.org  http://www.debian.org/~jwl/