--pgp-sign-Multipart_Mon_Apr__2_12:20:25_2007-1
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

At Mon,  2 Apr 2007 09:33:52 +0200 (CEST), Lasse Hiller=81=F8e Petersen wro=
te:
Subject: Re: Proposition for Releases page changes
>=20
> Personally I don't think it is the tools that matter.

Well for me, as a contributor to NetBSD, and third party developer using
NetBSD, the tools do matter when they effectively prevent me from making
useful contributions and when they hinder my ability to use NetBSD to
its full potential.

>  I know coding is hard, but writing good documentation is also
> hard.

Indeed, thus the need to make it easy to create, manage, and maintain
that documentation; as well as to use it once it's there.  Documentation
that starts out good but then isn't maintained and updated to be
consistent with the code becomes useless.  Good documentation is useless
if it cannot be easily used.

I'm complaining about the maintainability, managability, and usability
of documentation authored in XML.  Others have made similar complaints.
I don't know what all the reasons and excuses were for choosing XML in
the places where it is used, and without knowing those things it's hard
to balance the pros and cons of the choice.  I do know that we have a
large body of good documentation included in the base system that's easy
to maintain, manage, and use.  It is authored using any text editor,
maintained and managed using any type of text handling tools, and
pulished using groff(1) and the mdoc(7) macros.  It might not make the
prettiest web pages, but it makes decent on-line docs and excellent
printed docs, all using tools included in the base system.  There's also
a significant portion of documentation in the base system, albiet
primarily from third party sources that are integrated into the base,
which is authored using the Texinfo tools.  Texinfo docs can also be
easily authored using any text editor and maintained with any type of
text handing tools, and they can be published in web, on-line, and
printed form too, albiet only partially using tools included in the base
system.  While XML can be authored using a text editor, that's not so
easy to do manually.  However XML cannot be maintained and managed,
published, or even used so far as I know, with tools existing only in
the base system.

--=20
						Greg A. Woods

H:+1 416 218-0098 W:+1 416 489-5852 x122 VE3TCP RoboHack <woods@robohack.ca>
Planix, Inc. <woods@planix.com>       Secrets of the Weird <woods@weird.com>

--pgp-sign-Multipart_Mon_Apr__2_12:20:25_2007-1
Content-Type: application/pgp-signature
Content-Transfer-Encoding: 7bit

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 5.0i for non-commercial use
MessageID: Z3seprJF+A+NNlcuirA9wwXMi7IyFjFR

iQA/AwUBRhEtS2Z9cbd4v/R/EQI0WgCg577FECFzOA7IirDX6NampYd9rl0An1Fa
qKdWBxfsZcd+8DfBG7svbQk0
=xSe6
-----END PGP SIGNATURE-----

--pgp-sign-Multipart_Mon_Apr__2_12:20:25_2007-1--