Re: Documentation (was Re: PIL 4 Just Arrived!!!)

[Paul Merrell <marbux@...>]

On Sat, Oct 1, 2016 at 11:45 PM, steve donovan
<steve.j.donovan@gmail.com> wrote:

> I find that documentation requires a different mindset than coding.
> When you're in the flow, the code _feels_ like it's self-documenting,
> because all the context is fresh in the head. The trick is to go back
> later and fill in the gaps.

I think that optimally, documentation should always be "village
idiot-tested." That is, someone who has no familiarity with the code
should be tasked to use it, with careful note taken of the resulting
questions that are not adequately answered by the documentation, then
the documentation amended accordingly.

Or take it a step beyond and have end users write the documentation,
with the end user documenter questioning the developer on how to
perform tasks. That  approach has worked well for us on NoteCase Pro.
The documentation is now over 1,800 pages, with step-by-step
instructions provided for an enormous assortment of user tasks. <The
online version of the Help file is at
<http://notecasepro.com/help/help.html>.)

Best regards,

Paul


-- 
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]