Fw: Re: more people who write docs

[Two Ducks <twoducks@globalserve.net>]

I found this message on slashdot.org (Thanks to Roger for pointing it
out.) I just though the message was well written and could stand being
forwarded around a bit.

Ken

(Flame me if I shouldn't do this)
---------------->

            Re: more people who write docs
            by Matt Gushee (matt@it.osha.sut.ac.jp) on Monday May 11, @04:14 
            I don't know that there are too few people working on Linux documentation. Besides the man
            pages and info pages and HOWTOs, the Web is overflowing with Linux-related pages. But
            few of them are very helpful to beginners.

            I think many of the people working hard to document Linux have lost sight of a basic principle
            of writing, something most of us learned in our first English Composition class (or should
            have): know your audience. Even if your audience is primarily power users---how many
            people reading this can say they've never been frustrated trying to understand Linux (or other
            software) documentation? Noone, I'll bet. The information is all in there ... if only you could
            make sense of it.

            It's understandable why this happens. Becoming a skilled computer user takes, when you
            think about it, an enormous amount of detailed knowledge. And if you spend most of your time
            working with computers, it's all too easy to forget the huge and growing gap between your
            knowledge and that of the average drag-and-dropper.

            There was a fellow I worked with until recently, a Windows user, and I used to help him out
            with various and sundry computer problems. Most of the time we'd stay within the familiar
            territory of WordPerfect, but every now and then I'd have to walk him through an operation in
            another program. And sometimes I'd say "Okay, now save the file." And he'd respond in panic
            with "How do I do that??!" It took him the better part of 3 years to figure out that almost every
            Windows application has the same menu command in the same place for saving files.

            I'd hope most new Linux users catch on a bit faster than that, but nonetheless there are levels
            upon levels of knowledge. I consider myself reasonably skilled: I can do the tar, the tcl, the
            fdisk, the wa-wa-watusi [:-)] but a few months ago I exchanged email with a couple of
            XFree86 developers. When they started asking going on about video registers, I felt a lot like
            my slow-learning colleague.

            I don't want to criticize anyone. I know that everyone is putting a lot of effort into
            development and documentation. And the writers of old man pages, for example, thought they
            were writing for developers and sysadmins, and generally did a pretty good job of addressing
            that audience. But I think that anyone now writing documentation needs to take a little time to
            think seriously about questions like:

            * Who will read this?
            * What background knowledge do they need in order to understand my manual (or my
            homepage)? For example, if I refer to compiling a kernel, do they have any clue how to do
            that--or that it's not really all that hard?
            * If they don't have the necessary background info, how can I help them to find it?
            * If I have to plunge unsuspecting readers into a difficult topic, how can I ease the pain?
            * Can I assume my readers understand what this program is supposed to do, or how it works
            together with other parts of the system?

            The authors of the better-written HOWTOs seem to have asked themselves these questions.
            If all of us did, I think we'd have much better documentation for Linux and its software.