On 11/03/17 08:32, cbannister@slingshot.co.nz wrote:
Oh, come on! What you call good documentation means writing for a user who has no clue about what the program does.
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".
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.
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").