Re: SGML tools aren't so great

[Gary Preckshot <garrell@inreach.com>]

pac1@tiac.net wrote:

>Lets not worry if someone's a "nerd" or not.  Let's help them recognize how to
improve their writing by understanding their current and future audiences.

Actually, I'm a nerd and happy to be one, but I hear you and some people might take
it as a pejorative. "Nerd speak" is so descriptive, though.

>One of the difficult parts of writing documentation or anything else is
understanding what your own assumptions really are and how they differ from those
of your audience.

That's certainly the crux of the problem. I think a lot of them are not even
conscious of making assumptions. One of the central assumptions in the SGML debate
has been that anyone who isn't crazy about SGML couldn't possibly be a good HOWTO
author. In fact, it's those people who either don't know what SGML is or don't want
to know who should be the most sought authors. After all, spreading the Linux gospel
isn't going to be done effectively by authors who don't understand the wider audience
but do understand SGML.

>A lot of the documentation of these systems is about how things work, rather than
how to use things.

That's probably the most glaring assumption that permeates Linux documentation.
Certainly, something called a "HOWTO" should be oriented toward how to use things
with how they work inserted as necessary to explain how to use them. The HOWTO HOWTO
could use this advice. It goes on and on about the mechanics of various features of
how tos, but you never get a picture of the forest, just individual trees.

It's certainly the most obvious defect of the emacs help system. I want to quit. What
I want to know is how to quit. If I knew how to quit, I wouldn't be asking the "help"
system how to quit. Emacs help could use reorientation - deal with the basics of
editing and make them findable by terms ordinary human beings use to describe them,
like quit, find, save, delete, cursor, move, insert, you know, simple terms.

The HOWTO HOWTO should maybe address this issue. HOWTO authors would be more helpful
if they addressed how to first and why in later chapters. Instead, they follow the
usual nerd practice (there's that word again) of explaining everything adnauseum and
finally getting to the point. Maybe there should be a style manual.

Gary






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