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

[Daurnimator <quae@...>]

On 5 October 2016 at 16:18, Tim Hill <drtimhill@gmail.com> wrote:

> What I have been doing more and more, though, is to write the
> documentation as a document on its own concurrently with but
> slightly in advance of the code. I.e. the documentation shows
> the code as it ought to be, not as it is. Only a cynic can argue
> with that :-)

I have to confess I’m not a great fan of inline documentation, for two reasons. First (and let’s be honest here), developers often are not good at writing good documentation. Second, in our work, where source code is truly locked down, separation of document files and source files is necessary to allow late changes to documents after code lock-down.

Having said that, we take great care to structure our source tree so that source code and it’s associated document files live in close proximity.

—Tim

I agree. 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.

The main risk with keeping documentation separate is that code and documented behaviour can more easily diverge; though I can't count how many times I've seen code like: /* this function foos */ main() { bar() }

I try to keep code and docs at least in the same repository, that way you can e.g. enforce that pull requests change both code and docs.

For your access control situation you could hopefully just enforce that only the 'doc' *subdirectory* has edits after release?