Re: Use POD for docs! (was Re: HTML)
On Wed, 24 Jan 1996, Ian Jackson wrote:
> Tommy Marcus McGuire writes ("Re: Use POD for docs! (was Re: HTML) "):
> > Would glimpse help? It is a grep-like thing that can allow for spelling
> > errors and can build index files for a directory tree and search for files
> > based on that index.
>
> No. For a keywords-based help system it's very important that the
> keywords for each document are right. A full-text search, or a search
> based on summaries or keywords invented for some other purpose,
> doesn't work at all well.
Very true. Besides that you will need to agree on a set of keywords to
be used by the authors. I have seen this shortcoming with a large
documentation project with a lot of professional technical writers
involved using freely chosen keywords. Now every week the CD-ROM
containing the documents is accompanied by an article explaining what
keyword to use to access a particular article. I think this is not the
way to go.
I think the complexity in producing a good consistent set of documents is
highly underestimated. It is of a higher order than maintaining a
software distribution like Debian.
The dependencies between documents are (well, should be) higher than
those between software packages. Furthermore you have several layers
that can become inconsistent: layout (not that bad), structural elements
(for example the man pages vs info files vs HTML vs free-text),
navigational elements (i.e. hyperlinks, browsing sequences, indexes,
table of contents) and content inconsistencies.
Therefore it is not a question of HTML vs texinfo vs POD etc. It is not a
question of what type of navigation is best. It is all about using a
scheme that *garantees* consistency as well as presenting the information
effectively.
I think we should concentrate on:
1) what kind of information do we need,
2) how do we keep the maintainance distributed without sacrificing
coherence,
3) how can we use the existing documents as much as possible and yet
integrate them in one meta-document,
4) how do we keep the use of resources, both human and electronical,
low?
Ad 1. It seems to me that the discussion about the documentation is too
vague on what we would like to see. "A list of packages..." is not
scalable (I like to see Debian really big someday) and we do already have
that, be it distributed in a couple of dictories. Keywords are better
suited for the more experienced user, so that leaves the real novice in
the cold.
Ad 2. I think of a mechanism that can be called from a
post-install script. It should integrate some "man -k/Packages" like
description in the main document (not necessarily one and the same file)
with a link to the rest of the documents.
Ad 3. I propose the use of two mechanisms: a hierarchical index leading to
the level that in Ad 2 and an agreed-upon indexing network of keywords.
Ad 4. We should not do major rewrites, just add the necessary primitives
needed for a better navigation. For package maintainers that should mean
defining the place in the hierarchy of the meta-index as well as giving
keywords for the keyword network. Maybe new keywords are permitted as
long as they are inherited from a more abstract one. I think we should
look at other solutions before using yet another daemon like httpd.
I am sorry if I elaborated too much, but working at a firm specialising
in "information disclosure" I see too much documentation projects fail
because of a lack of analysis and design. Even small ones can suffer from
it.
Evert-Jan.
Reply to: