I finally understand.
The reason I've been unable to write good documentation all this time is who has been reading it. I write code that describes how to do something to a computer. That documentation must be excellent syntactically, all encompassing and as flawless as possible. It must also be complicated as the compiler/interpreter is generally fairly stupid and needs intructions for every step.
I have a tendancy to take that over when documenting the code, what I really need to do is say "This does x" rather than "This does y to z in order to get x to be the desired value, but has to take into account a, b, and c factors".
I finally understand - document simply and briefly to document well...
Permalink