Greg Woods wrote:
>At Sat, 31 Mar 2007 20:39:05 +0200, Martin S. Weber wrote: 
>> Now, some time later, users begin to complain about the quality
>> and outdatedness of our documentation.

Users complain. That's our raison d'etre. ;-)

>Let's not forget that we already had stunningly good looking
>typeset-quality printed documentation (if we wanted it) long before XML
>weaseled its way into more than a few places.

As a user, I must say that I am totally agnostic with regards to tools
used to make NetBSD, provided the result is good.

Also, I don't care one bit whether the documentation is good looking, or
bad scans of ugly handwriting - as long as the *content* matches the
quality of NetBSD itself.

For some reason I am not surprised that this has changed into a discussion
of formats. Somehow whenever there is a discussion on a difficult subject,
the easy way out is to start discussing syntax, notation or format.

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.

Wouldn't it just be great if we could make automated unit-tests and
regression tests for the verification of documentation? :-)

(Damn, announcing such beast would have been a terrific April's fool
message. OK, consider it a birthday wish instead.)

-Lasse