Thursday, July 2, 2009

Writing a technical document

When I write a technical document, I try to be careful to keep three things.

1) Do not use the term that hasn't been explained in the earlier pages.
I think this is a basic rule that every document must keep, but lots of them break it. I once read a document about a Python framework which uses a term "jelly" (is that case, it used the term in method names) with no explanation beforehand. It took me a long time until I know its meaning. I hoped if the writer had added just one line saying "jelly means serialize". (although the framework itself is very useful. Lots of its terms are named after a sandwich. You guess what it is? ;).

2) Do not try to explain two things at a time.
Human brains are not designed to think about two things at a time. When you explain recursive function call, don't take mandelbrot as an example. Think about an average reader and take an example that most reader is supposed to know.

3) "Make a list of stuffs to write, think about the explanation flow of the document".
I usually make a graph for 1) and 3), which has a set of circles, each circle contains one element of the list , and dependencies as arrows between the circles.

No comments: