Skip to content

Opinions on Writing Documentation

I’ve been writing a lot of documentation recently; I know I’ve gotten more opinionated about the topic.

Documentation is not one size fits all
Ideally all the documentation should be great, but it needs to be most relevant for the target audience. Developers get irritated by missing details that, if included, would bore management or consumers. Find out or decide who the target should be and try to make them happy. I may have it a bit easy in this regard for my day job – we’ve got a technical documentation group that takes our specifications and technical documentation and re-targets them for the user and programmer’s manuals.

It starts with the specification
I spend a lot of time getting the specification as complete as possible, and I spend more time keeping it up to date. Where I work, it is a necessity since we contract out some of the development. If it isn’t in the spec, it probably won’t get delivered. Beyond that, the spec help defines the narrative of the documentation and provides a lot of the material for future documentation.

When possible, write obvious code, not obvious comments
Don’t waste your time or energy writing comments for very blatant sections of code. Save that effort for the hard, quirky, or complex stuff.

Automated tools can cause crappy documentation
I’ve used automated tools like Doxygen or SandCastle to generate documentation for a few projects. They produce good looking documentation, but I don’t like them for two reasons: they are fiddly and they give you a false sense of accomplishment. You can waste a lot of time trying to get ‘perfect’ looking documentation when you should be actually documenting things. After you finally get things set up, the documentation can look spectacular — but it is just a gilded frame. When I’m in the middle of coding things, I like to write quick comments. I don’t want to stop so I can look up proper comment syntax. This may just be where I work – we don’t produce a lot of this type of documentation so I’ve never really learned one of the systems. I’ve seen very well done automated documentation, but you really need to buy into the system to make it work well.