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").