a unified documentation interface without overkill
From: Evert-Jan Couperus <couperus@reflex.simplex.nl>
> 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.
I don't think we're on the same wavelength :-) .
This is a recipie for failure. We are not mounting some tremendous
documentation project here. We simply want to present all of the available
documentation using one interface, with one top-level index. This should
be do-able in a month of evenings by one programmer. Once we have that,
we will have the leisure to start out on more ambitious projects if we feel
they are necessary.
> 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),
Inconsistent layout is easily tolerated by the reader. In the case of a
documentation department that is attempting to create a uniform look and feel
for an entire product, this is a valid consideration. That is not a goal of
Debian.
> structural elements
> (for example the man pages vs info files vs HTML vs free-text),
Given an HTML presentation of all of these different formats, the structural
differences are mitigated somewhat, although they do not disappear.
> 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.
Guaranteed consistency is not one of our goals at this time. We'd like
the reader to have some chance of finding the documentation and reading
it without having to be a Make/TeX/Roff/Lout/Latex/etc. guru.
> Besides that you will need to agree on a set of keywords to
> be used by the authors.
If you really wanted keyword search, why not simply use an inverted index
a la "refer" and then every word in every document is a keyword and the whole
procedure is automatic. I'm not convinced that we want keyword search, though.
> 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?
I don't think we can afford your standards.
> We should not do major rewrites, just add the necessary primitives
> needed for a better navigation.
We should not add primitives. We should not alter the documentation at all
except to run it through an automatic program to translate its format
when we present it. We should construct a top-level index.
> 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.
This sounds very complicated :-) .
> Maybe new keywords are permitted as long as they are inherited from a more
> abstract one.
The concept of "keyword administration" is probably outside of the scope of
our project.
> I think we should look at other solutions before using yet another daemon
> like httpd.
An HTTPd is only necessary if you want translation at run-time. If you
sacrifice disk space by having pre-translated files in place, you only
need an HTML browser using the "file:" URL, you don't need a server. In
any case, an HTML server is cheap compared to the alternatives.
> 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.
I'd rather have it Tuesday than have it perfect. I think after we've
satisfied the basic goal of having some way to read documentation using
one tool and one overall index we can spend as much time as we wish on
doing it right.
Thanks
Bruce
--
Bruce Perens <Bruce@Pixar.com> Pixar Animation Studios
Toy Story: > US$174M domestic box office receipts so far.
One Oscar so far (in the Special Achievement category).
Reply to: