Re: geekness

[John <jcj@spiretech.com>]

At 01:08 PM 5/27/00 -0400, you wrote:
>At 09:20 27/05/00 -0700, you wrote:

>Everytime I hear people complaining of the "geekness" of LDP documents, I
>ask myself a question : what can we do?
>
>You need a technical background to write documentation, and we can't
>afford translators.
>
>Maybe should we ask newbies a hand to translate our documents to common
>english?

Newbies as translators is one idea that might work, if you can get enough
of them. The amount of work involved would be roughly equal to the work the
original authors put into writing them in the first place. Remember, the
newbie needs to *understand* the material before he or she can translate
it. There's quite a bit of study involved in order to do that. You can't
just sit down at a split screen and retype the stuff.

Then too, the newbies probably would have no idea how to code SGML. If you
make knowledge of SGML a requirement, you won't get many newbies. More
likely someone would have to rework their translations into the standard
LDP format.

Gary suggested that LDP authors could simply learn to write better. That's
another suggestion that might have some merit. It won't work for all, of
course. Some LDP authors may not have the time, others may not have the
inclination, yet others may not be able to do it at all.

Toward that end, I can offer one suggestion that would go a long way toward
assisting LDP authors to improve their writing -- you need to think of the
audience as you write. If you are writing for other technogeeks, then you
can go ahead and use the vocabulary of Geekspeak. If you are writing for
someone who just installed Linux yesterday and can't get the network card
working, you're talking a whole different level. You can't just say "you
need to configure eth0." You have to explain what "eth0" is first. And that
explanation may require an even more fundamental explanation of something
else. Whenever I have taken documents and "translated" them, I end up
usually with at least twice, usually three times the verbiage of the original.

I think a lot of technogeeks think that good writing involves grammar,
punctuation and spelling. Or maybe that it has something to do with style,
e.g., writing for newbies needs to be humorous in order for them to
appreciate it. These are misconceptions. Not that there is anything wrong
with good usage or a humorous style, but those are not the deficiencies
that newbies are complaining about. They are griping because they simply
can't understand the language. It goes right over their heads. In this
respect, the number one sin is failing to define terms before using them.

Another suggestion would be to try to incorporate troubleshooting as you go
along. After explaining how to do something, think of the possible things
that could go wrong. Then add a few paragraphs explaining these issues and
the known fixes. Troubleshooting should be right there where the user can
find it. (And this is as big a problem with Microsoft documentation as for
everyone else -- if it doesn't work, you have to dig all over the place to
figure out why. Linux should be better than Microsoft. Linux should be
better than all of the others, too. That's the goal, anyway.)

I don't think there is one, single solution to the geekness of
documentation. It's just something that LDP authors have to keep hacking
away at. At least everyone recognizes the problem. That's the first step.

And if there is something that would make a marketable printed book, I'd be
interested in working with the author to translate it for our mutual gain,
and profit to the LDP fund as well.


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