--pgp-sign-Multipart_Sun_Apr__1_13:24:13_2007-1
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

At Sat, 31 Mar 2007 15:52:58 +0200, Martin S. Weber wrote:
Subject: Re: Proposition for Releases page changes
>=20
> On Sat, Mar 31, 2007 at 02:24:21PM +0200, Zafer Aydogan wrote:
> > Yes, NetBSD documentation has always been a pain.
>=20
> Well, it was okay some time back.

The worst pain in the NetBSD documentation is that it suffers greatly
from being out of date.

There's also the minor problem that some developers seem to be able to
push in changes and new features without accompanying documentation.
IMNSHO no code is worth committing until it is _fully_ documented, but
at the very least those that are apparently reviewing it could at least
call for minimal manual page entries and extensive, complete,
cross-reference updates.  I'm not saying everything goes in without
documentation, but it happens far too often it seems.


> > And trying to help improving is a pain too. You need to send xml diffs !
>=20
> And that's where the project lost me as a contributor. You want XML?
> Go find the people who want to edit that. Not me.

I couldn't agree more.

For example I had some edits to the pkgsrc guide document that I thought
would be useful and interesting to everyone, but when it went XML I
found it impossible to even continue to merge my changes from one
quarterly branch to the next, let alone get them in shape for
submission.

I thought mdoc(7) provided all the necessary features for simultaneous
publication of documentation in various forms, and in my estimation it
is (luckily still) the most common way of authoring NetBSD
documentation.  (perhaps even without counting the "man" pages)

If folks want more structured (and truly structured) documentation then
I could only recommend Lout (pkgsrc/textproc/lout) as it is light years
beyond anything-TeX or troff-like and still light years beyond
anything-ML too.

I'd personally be happier with raw troff or even raw TeX than
anything-ML.  There's nothing in the textual/documentation world more
difficult and more complex to read, parse, or manage than *ML files.
Nothing.

I was once, thankfully only very briefly, in awe of SGML after attending
several presentations by one of the SoftQuad founders.  However once I
looked into the nearly super-human effort necessary to build tools from
scratch that handle it, I quickly gave up on SGML.  I bit my tongue when
the WWW went with HTML, but it's too sore to bite again.  One can
produce the likes of HTML from truly structured documentation without
too much trouble, so long as one doesn't have to parse again and/or
modify what one generates.

--=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_Sun_Apr__1_13:24:13_2007-1
Content-Type: application/pgp-signature
Content-Transfer-Encoding: 7bit

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 5.0i for non-commercial use
MessageID: ax7MgGozuQTF0IGM3IN5qoSRkjLoZpwY

iQA/AwUBRg/qv2Z9cbd4v/R/EQIuqgCfZ489kFTUpWYvrpRVS/SMe0bcXxcAn1mO
Xib4Bo6ihXN8c+yDAaQmOCt8
=MgXR
-----END PGP SIGNATURE-----

--pgp-sign-Multipart_Sun_Apr__1_13:24:13_2007-1--