Mailinglist Archive: opensuse (4020 mails)

[Randall R Schulz <rschulz@xxxxxxxxx>]

Steve,

On Monday 11 October 2004 07:16, Steve Kratz wrote:
> ...
>
> A lot of Linux documentation seems to be like that - They often expect
> a certain base knowledge that makes even a simple subject difficult if
> you don't know where to find the other knowledge.

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.

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.


Randall Schulz