Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal")

[deloptes <deloptes@gmail.com>]

Martin Read wrote:

> That kind of documentation is *really important*, because that's a big
> part of how people who don't know how to use the software learn to use
> it; not everyone has a learning style well suited to beating their head
> against the brick wall of "all the documentation assumes you already
> know exactly what you want to do and just need a refresher of what the
> relevant command-line options are".
> 

When you do something, you usually set a scope. You make some assumptions,
you define your audience.

> Unfortunately, many programmers (and even a fair slice of experienced
> documentation writers, both professional and volunteer) are utterly
> hopeless at writing that kind of documentation, even if they're good at
> writing reference documentation for people who already know how to use
> the software.
> 

I don't think so. It's simply that no one has time to write for each kind of
audience. usually writing documentation is done to explain how and help use
a piece of software. Everything that you lack in knowledge to understand
the document must be compensated by you and not by the one who wrote the
documentation.

> Well-documented software has multiple kinds of documentation: external
> reference documentation for experienced users, tutorials and other
> introductory documentation for inexperienced users, internal reference
> documentation for developers wanting to modify the software, integration
> documentation for using the software as part of a system with other
> software, ...
> 
>> Imagine a recipe written for a user who has no clue
>> about cooking ... I mean where do you start? You
>> HAVE to assume the reader has a certain level of
>> expertise.
> 
> There are, in fact, cookbooks (and cookery programmes on television,
> etc.) aimed at people who have no clue about cooking (yes, sometimes
> even at the level of "this is how you bring a panful of water to the
> boil").

If you are willing to improve the documentation of any program, you are
welcome to do it. There is established way in doing this and it is done
constantly. You could propose a patch to every free software program and
hopefully this patch will be accepted by the maintainers.

You must bear with the people that are working for free and making this
happen every single day.

regards