Software Development/Documentation

When you're coding for yourself, it's easy to forget about documentation, since you know how your code works and how to use it, and if you forget, you can reread it and figure it out. Deciphering your own code is annoying, but possibly less annoying than writing documentation. Usually when I'm in my lazy, non-documenting mode, I wait to comment pieces of the code during especially painful rereadings. I'd like to be nicer than that to people who aren't me.

Documentation comes in several different kinds, based on its location, format, and intended audience. It might help to think of documentation as falling into two basic genres: cookbooks and references. References tell you how the project works, and cookbooks tell you how to navigate through the project to reach particular objectives. Tutorials, for example, are a type of cookbook. Audiences fall into about three main categories: end users, API users who are developers using the code to write plugins or outside apps, and project developers.

As an overview, here's my take on the purpose and audience of documentation types you might find in Python projects, though most aren't limited to Python. Afterward I'll list links that discuss each type in more detail.

• READMEs - In a document in the root directory of the project. A cookbook that tells users and developers the basics of working with the project.
• Docstrings - Mostly at the top of a function. A reference that tells API users how to use the function.
• Command Line Help - In the docstrings of command handling functions and at the top of a script. A reference that tells the user how to use the script and its command.
• Comments - Interspersed among lines of code. A reference that tells project developers what the code does and why.
• Code self-documentation (see Comments) - Elements of coding style aimed at communicating the code's intentions. A reference that tells project developers and API users what the code does. Some developers try to substitute this technique for comments.
• Project Documentation - In documents separate from the code. A cookbook and reference that gives users and developers thorough information for working with the project.
• Literate Programming - Interspersed among chunks of code. A reference that gives developers detailed explanations of the reasoning behind the code. This type of documentation isn't common, but it could be a good idea for some projects.

General advice

• Documentation - The Hitchhiker's Guide to Python - Covers a lot of these documentation types.
• Documenting Python - Python Developer's Guide - Python.org - A style guide for the Python source code, which could be adopted for other projects.