next »

[Wilson Saunders]

I have just finished a major project for my company and have decided that I should write a long winded technical doccument explaining all the counter intuative programming techniques I used to create the thing. I commented my code as I wrote it but I feel an obligation to write down where in the code certain critical events take place. Needless to say this is boring me to tears.

Has any one here had to write technical doccumentation for their code? What kind of stuff can I leave out?

For those of you who have read technical doccumentation of some one else's code before having to work on it, what did you find most helpfull?

Realy I am just posting this as a rant to avoid writing more in that damn doccument for a few minutes.

[bateleur]

Has any one here had to write technical doccumentation for their code? What kind of stuff can I leave out?

Yep. I once had to write a handover document when passing on a project I'd been working on for three years to a newly-hired co-worker who'd never even used the language before (it was a proprietary assembler variant).

The most important thing is to provide a broad overview of the main elements of the software in terms of both data flow and control flow. There's no need to include every detail. In fact too much detail is actually harmful, because then the document becomes intimidating to read.

Make sure you structure the document as much as possible so that the contents page or index can be used to quickly find information on specific, key topics.

Where you've used some weird coding trick this is usually best documented entirely in code comments and needs to be done in such a way that it's as hard as possible to miss the relevant comment whilst inspecting the corresponding code section.

Lastly, remember that most halfway decent programmers automatically go for the source when trying to understand how something works. Your docs should aim to support someone reading the source, not act as a substitute. (This point is somewhat controversial, but people who disagree tend to wear suits, write bad code and/or have a productivity rate that would make sloths look speedy.)