The blog and home page of Simon Soanes
Skip to content
[ Log On ]

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