Everyone hates documentation. It is either boring or it doesn’t answer provide the needed answers. Many programmers agree that documentation is critical when they are taking over a project for someone else, and think it is completely unimportant when they need to create it themselves.
So as a customer: what documentation should you expect or require from your programmer?
Every situation is different, but here are some documents you may want to consider requesting:
System Design
This is the specification that was (usually) created before the programming began. It can include functional specifications, wireframes, screen mockups, user stores, UML diagrams, screen to database field mappings, etc. The good news about system design is that it can really help the developer understand how the application started. The bad news is that over time, it can get pretty stale unless someone is keeping it up to date.
In most cases I work with my customer to create a system design before programming begins, but this is not always the case. If a system design is provided as part of the project, make sure you request the most current version when the project is completed.
Overall System Setup and Configuration
This is “what if I’m hit by a bus” document. Its purpose is to allow another programmer to set up the application on their system with a minimum amount of pain. It should include:
- A high-level list of all components and/or modules
- The language and version used for development (and the IDE used by the current developer if appropriate)
- The database in use and its version
- The operating system in use by the current developer
- The deployment operating systems currently supported
- Any third party component used and their versions
- Any third party or other tools used for code generation or build
- The database schema
A good programmer knows that this documentation can smooth the transition to another programmer, and that it is your right to want to minimize vendor lock-in. Don’t be uncomfortable asking for this documentation.
The “Why” Document
Every project involves decisions. Some decisions are obvious (we built a web app because we needed to give external users access to the data) and some are arbitrary (we wrote it in PHP because that’s what the programmer knows). Documentation that covers the “why” for the important decisions can help the next developer understand how the project evolved and can help them to not cover the same territory. For example:
- Why we used a third party component instead of the built-in component
- Why this service pack is important
- Why a particular routine has an ugly hack in it
- Why this table’s naming convention is different from the others
Some of these “why’s” may belong in the code comments as well.
Function and Subroutine List
When programmers are asked for documentation, sometimes they use a generator to create a list of all the functions and subroutines in the system, with a description of each. While this can be relatively easy to generate, I’ve found its usefulness to be fairly limited. As a programmer, I rarely look at this type of documentation.
End User Documentation and/or Help Files
Depending on the application, this can add a lot of value to an application. It can provide that polish that takes the application to a professional level.
However, many programmers have trouble thinking like an end user. (Remember, many programmers are aliens.) And creating this type of documentation can be expensive. So before you decide that the programmer should provide end user docs, ask if this is a service they provide. And ask to see examples of other user documentation they have created. Then decide if it makes sense for the programmer to write end user documentation or if it should be created by someone else.
Creating documentation takes time. Think about what kind of documentation you want before the project begins and make it clear to the programmer what you are expecting. That way it can be included in their bid.