On Mon, Apr 02, 2007 at 04:25:25PM -0700, John Nemeth wrote:
> (quotes snipped)
>      As has been explained before, you don't have to use XML, you can
> submit documentation updates in pretty much any reasonable form (i.e.
> XML, HTML, plain text, a simple description of what needs updating,
> etc), so how exactly are the tools chosen by the people charged with
> maintaining the documention hindering your ability to contribute?

What needs updating?

Ok, please convert the documentation to a less verbose format which
will not load the creative's mind with a full ruleset of bullshit.

Oh wait, you can't do that without me sending patches, right?

Ever thought about that there are other people who want to work on
YOUR HOLY DOCUMENTATION and thus the tools chosen by you people
DO matter.

Seriously. Watch the average time-of-rotting of the average patch
directly changing the source language (be it C, roff, html, list, xml).
Reason? Lack of manpower, lack of enthusiasm, lack of whatever.

Send in a note, hey on page 221 in your guide's PDF. What a mess! The
screenshot belongs to two pages earlier and the wording of the bottom
half of the page - do you have native-speakers, too to write your doc?
I suggest copying the relevant paragraphs from man xxx (2nd and 3rd)
at that place instead.

Whoa, quite a simple, even partially constructive description of what
needs to be done. But before that'll happen, the rest of the SA bugs
will be fixed by ad, 1:1 removed again and openbsd.org run on NetBSD.

Realistically, docbook(-xml) might be a good vehicule to ride on, but
if it's not sexy enough to attract those fiddly-mind users who find
the nits in the doc and even have the nerve to think about what should
stand there instead, it's the wrong vehicule to ride on.

Once there was that mail from hubertf about the wiki / docbook export.
If the language is ugly, maybe do as the industry does and write your
panacea around it. Maybe that'll be sexy enough for the ppl mentioned
above.

I'm out of here now (sorry for that last one being late) and will happily
send in simple descriptions of what needs updating. 
Bon appetit with your food.

-Martin