Originally published by Robert Beisert at fortcollinsprogram.robert-beisert.com

CS 101 – Document Everything

If I hand you a black box with one unlabeled button, what do you think that box can do? How do you think the box works?

Unfortunately, programs are essentially black boxes. Unless you have either written or read the entire source code, you can’t really know how the system is supposed to work.

This is where documentation – a description of the program written for its users – comes into play.

User Documentation

Every program should come with some form of manual which describes how the users can work with it. If it is a terminal-based program, such as the Linux commands “gcc” or “cd”, we usually include a help option (–help) which tells the user what arguments the program accepts and how the program works.

User Documentation can also be in the form of wikis, “Dummies” guides, and YouTube videos. Basically, anything which helps the user counts as user documentation.

System Documentation

System Documentation is any documentation that helps programmers modify and work with the program.

The simplest form of system documentation is probably function documentation, done with tools like Javadoc or Doxygen. This documentation describes what a function is supposed to do and what each function argument is supposed to represent. Every system should, at bare minimum, have this kind of documentation.

If we’re particularly nice, we will also include our analysis documentation, design documentation, and testing results. This lets the programmers trying to maintain our code see how we developed the program, and where we might have failed.