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

[steve donovan <steve.j.donovan@...>]

On Sun, Oct 2, 2016 at 2:56 AM, Valentin <vsl@dasdeck.com> wrote:
> Incredible! My guess: those guys can't be coders (which are supposed to
> hate documenting stuff!), but must be accountants, humanities scholars,
> writers or the like ;-)

I think the secret is collaboration between people who like to code
and people who like to document. The rendered documentation looks very
handsome:

https://doc.rust-lang.org/std/result/

(Which is why I'm always calling out for new style input for LDoc)

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.