Re: Pictures in the docs and website

[David Kastrup]

Jan Nieuwenhuizen <address@hidden> writes:

> Graham Percival writes:
>
>> No argument there!  Yes, more documentation about maintainability
>> the better.
>
> I hope you're joking...  The less documentation needed, whether it be
> for program usage, describing program bugs, build or release process,
> or maintainability, the better.  No one likes to read documentation.

It beats reading code.  Code is written for computers, documentation for
humans.  Computers are perfectly able to get along following
instructions.  They don't need to understand anything.  Continued
development and maintenance, in contrast, requires understanding.

> What is really bad, is a situation where doing one of these things
> becomes some sort of puzzle, maze, time sink of trial and error, that
> could have been avoided by adding or sharing some minimal piece of
> documentation.

If you take a typical look at Keith reviewing Mike (happens only if the
reviewing period time of a patch stretches over a weekend where Keith
has time), you'll find that Keith is asking a number of questions about
how the code is supposed to work that are documented nowhere.  Mike then
congratulates Keith on figuring out the puzzle correctly (or not) and
everybody is happy.

Again and again and again.  Drives me nuts.

> However, documenting something that can also be automated is bad.

Sure.  Having to make decisions is work.  A good interface will offer
only decisions for cases of fundamental different nature.  Not decisions
about picking between two choices doing the same job with different
shortcomings.

> Fixing a bug is much better than adding documentation about how to
> work around it.  If you are tempted to document something, start with
> /why/

Sure.  That's the one thing one does not need to tell the computer via
code.  But that is still part of the story.

-- 
David Kastrup