Documenting Your Project

You have documented your project, right?

Sure you have, you added comments to your code. That should be enough!


An old saying, perhaps a bit too brutal for some, goes like this:

Pretend the person you has to maintain your code is a serial killer who
knows where you live!

If that makes you nervous, perhaps that is a good thing.

Good Documentation

Some folks will tell you that well written code says exactly what the program will do. I agree with that, but that is not the point of documentation. Good documentation explains why the code was put together the way it was, and anything else thta will help that maintainer keep from wanting to hunt you down!

The thinking you were doing as you wrote yur code is very important to that maintainer, who may need to fix a bug, or add a new feature. If the maintainer do not understand how you put your code together, staring at those lines of code will not help. The entire program may need to be studied to see what can be done to keep this thing running!

Documentation Tools

There are a number of tools that help you set up nice documentation for your project. The one I recommend for any project, and the tool I use for all of my course notes (including this one) is the Python Sphinx package. Although this tool was developed to support documenting IDE/index n, it is in wide use in many different reas. It does need Python to be available on your system (but that is not a bad things to do anyway!.

Here are notes on installing Sphinx- and getting your documentation going