The Monday 2004-10-11 at 11:30 -0700, Randall R Schulz wrote:
That's true, and it can hardly be otherwise. If each piece of documentation must stand alone and cover every conceivable necessary piece of supporting knowledge, then all documentation is essentially a tutorial. And that may not be so bad for new users, it's another kind of nightmare for experienced users who just need some details or to refresh their memroy about a piece of software with which they're basically familiar.
There are good samples of documentation. For example, procmail: cer@nimrodel:~> apropos procmail procmailsc (5) - procmail weighted scoring technique procmailex (5) - procmail rcfile examples procmail (1) - autonomous mail processor procmailrc (5) - procmail rcfile procmail (1) is the main one, and difficult to understand. But then, procmailex (5) has enough samples to start a newbie - I know, I was once one, and I configured procmail with that page. The difficult one was knowing about "apropos" :-P Mmm, well, no... procmailsc is more dificult. Another good one is fetchmail, the page is large, but it contains examples. Then, some programs have a "cryptic" man page, but then they have an extra documentation, faq or howto in the corresponding /usr/share/doc/packages/* directory. One such could be postfix.
I'm not suggesting that Linux documentation is complete. (Although for all I know, it really is and I've just failed--repeatedly--to find certain information.) Writing good documentation can be almost as hard as writing good software, and as you suggest, the skills of a good programmer do not in themselves constitute the skills of a good technical writer. In reality, it's not particularly common to find those disparate skills in a single person. Add to that the multilingual nature of the user base and you've got quite a large documentation challenge.
That last thing can not be sufficiently stressed. How can you tell somebody to RTFM if they can not read English? More translators are needed. For example, I, and some others, are helping to translate part of Togan's susefirewall howto, and I find it difficult (it is my first translation), but I find even more difficult finding resources to help me out: like proper free dictionaries for technical expressions, translation glossaries, manuals of style, and such. And surely, I'm not the first or only one translating things. -- Cheers, Carlos Robinson