On 2007-04-02 lhp@toft-hp.dk wrote:
> Personally I don't think it is the tools that matter. The problem is more
> of a political or temperamental one. I have worked enough with developers
> (at my work) to know that they have a tendency to focus on the code, and
> also a tendency to skimp on the documentation. This is an observation, not
> a criticism. I know coding is hard, but writing good documentation is also
> hard. Perhaps the curse of documentation is that when you write it, you
> have the least need for it, and when you need it most, you are - almost by
> definition - unable to write it. After all, if you could write it, you'd
> have no reason to read it. The obvious corollary for revising and editing
> outdated or incorrect documentation is left to the reader.

  IMO, the tools do matter; it is important that a general purpose
operating system have a good general purpose formatting/typesetting
system.  I don't think that documentation is significantly different from
anything else a formatting system would be used for.

  Often when users complain about documentation the real issue is that the
user has not tried to understand the coherence of the system enough to
find the available documentation.  I won't claim that NetBSD documentation
is perfect, but I usually find it to be one of the strengths of NetBSD.
When something is missing, it is usually an example needed to make sense
of the command line option descriptions.

  IMO, the number one usability problem in NetBSD is the lack of command
line and graphics integration.  However, as much as I dislike X I find
that documentation is available and understandable when the distinction
between X Windows and the rest of the system is realized and the coherence
of X considered separately.

  I don't like the roff system, but haven't found anything I like
significantly better.  What I would really like is something regex based
where the formatting is defined outside the text being formatted so that
you can read and write unbroken text in a text editor.

Matthew Orgass
darkstar@city-net.com