One of the planks of the Agile Manifesto states, “We value working software over comprehensive documentation.”
Unfortunately, people working on the project take this to mean that working software is sufficient and there is no need for any documentation. This could not be further from the truth. What do you need to document? In this article, I’m going to give you some suggestions for deciding what needs to be documented outside of the comments in the software (and yes, commenting your code is still useful as long as you focus on what and why, not how), and what got captured in in the ticketing or project management tool.
There are three places where you can create the most value when doing documentation outside the ticketing system:
- Tracking Decision Making
- Meta Data about the Project
- Process Integration
Tracking Decision Making
Typically, tracking of decisions that the team made in each story happens in the Project Management System or in a system like JIRA or TFS. However, there are times where it will be useful to have a summary that captures the major decisions, who made them and why. This can come in handy during the maintenance process where knowing why the team made a specific design decision may be the difference between changing a variable and rewriting a whole section of code when a change is required.
It can also be helpful during reviews and project post mortems when it can be essential for capturing lessons learned during a particular sprint. A simple way to approach this is to use a list in Sharepoint or an Excel spreadsheet with the following headings:
- Description of the issue
- Summary of Discussion
- Decision Made
- Effect of Decision
Metadata About The Project
Often, much of the information about the application will be self-contained, which is perfectly good as long as you have the hood up and can get at the wires underneath with ease. There will be times however, that having the application be a black box is going to cause issues for people who work on the application later. Even though applications are supposed to be black boxes, it’s good to keep notes on where the keys are so if you need to unlock the box later, you can.
Information that can be helpful in this instance includes:
- When the application went into production
- Location of the source code
- Location on the network where the production application is located
- Database connections or at least which database contains the application data
- Business Owner – Who has the authority to make decisions about the application?
- External Web Services or FTP servers that are used and any credentials needed (We store credentials in a central password vault)
- Any coding standards used (this can be very useful when the work is being done by contractors who may not be available for maintenance work).
- Any off the shelf applications that may be part of the system. This can be especially important when the off the shelf application gets an upgrade or has the version in use deprecated.
I am a big fan of process documentation. As one mentor told me, “If it’s not documented, it’s not a process, it’s a regularly occurring event.” ISO-9000, one of the most popular quality standards devotes several clauses to documentation. Process documentation provides a record of the baseline of your process, which you can then use to monitor changes and how well those changes worked.
When dealing with a new system, I like to know how the user will do the process with that system, not just how the system works. When I’ve taught software classes in the past, I’ve focused on a task and how to use the tool to perform that task rather than just how to use the tool. For example, when I taught Powerpoint, I taught how to create effective presentations using Powerpoint, rather than just teaching Powerpoint.
I personally prefer to use flowcharts for process documentation, but depending on your industry and regulations, you may have to write something more formal. The most important things to document when writing process integration documentation are:
- What job title does the process?
- How many people do the process (useful later when prioritizing trouble tickets)?
- Can the process still be done manually or via a work around if the application isn’t working?
- What are the inputs and outputs for the process?
- Are there feedback loops to let the person who created the input or output whether there was an issue?
- What is the value created by the process and how does the software contribute (this is something that you probably did during the requirements phase, but it’s good to go back and review to make sure something didn’t change in the meantime.)?
- Keeping some kind of history of changes and so forth can also be very helpful.
How Much is Too Much
One of the reasons that working software is valued more than comprehensive documentation is that comprehensive documentation is a huge consumer of project resources, both in creating the documentation, and in maintaining it. Massive quantities of documentation can result in binders full of information that no one will actually end up reading, or that will be out of date almost immediately. Keeping documentation at a useful level is very similar to writing user stories for a software project.
As a Developer
I need to be able to easily find metadata about an application
So that I can start working on maintenance tasks immediately when asked
As a Project Manager
I need to be able to see a history of decisions made about a project
So that I can improve the decision making process
As a User
I need instructions that show me how to do my job with the application
So that I can be productive immediately and reduce my learning curve
Albert Einstein addressed documentation and software design when he said “Everything should be made as simple as possible, but no simpler.” Understanding the value of what you document will help you do just that.