Archive for January, 2007

Documentation is not just another phase

Friday, January 19th, 2007

Documentation is often considered a distinct phase of software development. Very few admits enjoying documentation. It’s become the dark side of development which is most often tried to be left undone. The excuses are many, misunderstood agile software development processes being one the most recent. “We use Extreme Programming – we don’t make any documents!”

If documentation is kept as a separate phase, performed after coding, we will face similar problems as we do if testing is postponed until coding is finished:

  1. When we run out of time, the phase in question won’t get done
  2. The phase will be an enormous effort and unpleasant as such, we are coders after all. Documents are easier to write in smaller parts. For example, writing down what you have accomplished this day isn’t such a big deal. It’s easier to write when you still remember what you were thinking.
  3. The task is easily given to someone else. It’s most efficient when the same person wo wrote the code, also writes the documentation.
  4. The outcome of the phase are of no use to the previous phase: if documents are written/tests done along with coding, it will be profitable immediately. You’ll think about your code from a different point of view and you may even find a major flaw in your design!

I hear often “I’ll document the code when it’s finished”. But as often the code will get taken to production before it’s ready. And at that point there’s no documentation.

So, always document your code as you make progress!