What Makes for Good Documentation

Documentation is a vital part of developing and using a computer-based system. In some commercial organizations, 20 to 40% of the total development effort goes into the documentation of the new system, recording how the new system is to work and how it was developed.

Documentation is generally considered the second to last stage to software development. However, the sentence “You need to create documentation for this project.” Is generally immediately followed by groaning and cursing from the programmers. Documentation is tedious work, but the quality of your documentation will make a big difference in the quality of your project.

Don’t Assume They Know

Being a documenter, you must assume that the developers who are going to read it really are just beginners. This not only makes it easy for the actual beginners to get started but also for the seasoned/experienced developers to breeze through the documentation. If you do assume something tell the reader that you are.

Examples, Examples, Examples

I cannot stress how important it is to include more than one example for the project you are documenting. They are so important because the examples give context to the documentation. This can also relieve some confusion if the documentation is fairly wordy.

Document Workarounds

If you have known issues/bugs in your library or program, provide documentation for a temporary workaround. However, make sure to notify the reader that there will (hopefully) be a better/more efficient/more correct way to do it in a future release.

Put Personality Into It

Nobody wants to sit down for hours reading a step-by-step list that sounds like it was written by a robot. A common statement that I hear from my friends is that “Documentation is boring.” However, that doesn’t have to be true. I know the Django Documentation has several (nerdy) jokes in it, but it still puts human quality into the documentation.

Flashy Content, Please

Pictures and videos do fantastic for marketing, so why not use them for documentation? Try using screenshots or screencasts showing how to do various tasks in your project!

Your documentation can make or break your project. It is the object that tells users how to use your product. Without it, your project means nothing. There area tools like Sphinx that can assist you in documenting, however make sure that it doesn’t start to sound like a robot wrote it!