Re: SGML tools aren't so great

[Gary Preckshot <garrell@inreach.com>]

Tom Fawcett wrote:

>But I'm genuinely confused and mystified by the (occasionally expressed)
implication that writing and maintaining documentation really isn't
much effort.

If you look at the HOWTO HOWTO, for example, there isn't much there except text.
It said to contact the HOWTO coordinator, but there was no URL nor did it give
you a direct link to do it. All-in-all, underwhelming. Typical nerd speak,
assuming the reader knew how to do a whole bunch of stuff, and never really
explaining it or providing links as is so common in the HTML world. Even
Microsoft does better. I'm not advocating we follow Microsoft's practices, but
it's really inobvious from the LDP website that there's anything special.

Writing documentation is difficult, but the difficulty is avoiding blathering on
and not giving useful information. I don't read documentation to find out how
much a nerd knows, I read it to solve a problem. Nerds write documentation to
show off. The typical Microsoft nerd lists all the menu choices and then
slavishly describes each one. If you knew what they called it, you wouldn't need
to read the doc. If you don't know what they called it, you can't find it. Nerd
speak. Linux has it too. Apropos is the only saving grace. In fact, it's the
best, maybe the only, way to find things. And it's no better than Windoze. Did I
ever tell you how atrocious emacs is. Every so often I screw up and type edit in
character mode. Suddenly I'm in emacs and I want to quit. Finally I get to emacs
help. I ask it about quit. Does it tell me how to quit. NO! I have to remember
the emacs command to quit. But if I could remember that, I wouldn't need help.
Pure nerd speak.

So go the LDP website and tell me what's special, why is it so much better than
other websites that don't use SGML? Why are the HOWTOs on the Linux distribution
so much better than other doc. As far as I can tell, they're nothing special and
it's as hard or harder to find things than any other doc.

Gary


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org