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

[Dirk Laurie <dirk.laurie@...>]

2016-10-05 8:40 GMT+02:00 Daurnimator <quae@daurnimator.com>:

> I think you need to be in a very different mindset to write documentation
> than code.
> If I'm in a code-writing mindset then my docs just come out as an english
> 'port' of the code.
> Good documentation is much more than that.

There are at least three levels of documentation, aimed at different readers.

1. End users of an application.
2. Programmers that require a module.
3. Code maintainers.

These IMHO belong in the following places.

1. A nice HTML, PDF or man page. Tools exists (texinfo, pandoc, etc)
that can deliver any of those from one editable source.
2. LDoc compatible comments, also visible to ihelp. (I must get
a plug in. :-)
3. Comments in the code itself formatted in a place or a style that
LDoc will ignore.

The corresponds with how frequently the documentation should
change.

1. Very rarely.
2. Occasionally.
3. Frequently.