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

[Paul Merrell <marbux@...>]

On Mon, Oct 3, 2016 at 5:09 AM, steve donovan <steve.j.donovan@gmail.com> wrote:
> a non-trivial project needs a
> Librarian to keep entropy at bay.

Definitely. Also to ensure some consistency in writing style and level
of detail. We ask users to submit documentation contributions via the
mailing list and then Daniel or I apply the necessary rewrite if any
and then classify the contribution.

We have an big advantage on the organizational aspects because the
program is an outliner so our users are self-selecting for those with
a bent for classification of topics.

> Good documentation is measured, not just by coverage, but different
> level-of-detail views. First looking at a project, you want the 10,000
> metres overview, and then drill down to the details.

Yes, although you may need different types of details depending on
what your code does. With NoteCase Pro, for example, in addition to
the overview we needed documentation for individual user actions
(their locations in the GUI and a description of what they do) plus
instructions for "how to" tasks that require multiple user actions.
(The latter link to the former so I can maintain a single editing
point for an action's location in the GUI; locations sometimes
change.)

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.]