According to the Agile Manifesto – the benefit of working software and individual interactions are more essential than comprehensive documentation and processes and tools. Following these principles, teams should rely on highly effective face to face white boarding sessions rather than a single person producing a huge technical document. The end goal must be to communicate with the team and stakeholders.
But can documentation deliver value? Yes it can.
There are 2 core conditions that need to be met in order for your typical technical document to be a valuable asset to your team.
- It must be relied on over time. Most technical documents are rarely, if ever, referenced after they are created. Most of the information in technical documents is useful in helping you understand the design at a high level: sequence diagrams, details on the rationale behind decisions. However, they contain very little that teams can leverage for the day to day development of applications.
- It must be kept up to date. Documentation can quickly become outdated if it is not updated regularly. This is also fueled by a failure to meet the first condition – lack of use.
In order to avoid these pitfalls, approach documentation like you would an Agile project:
- Identify who will be the “users” of the document – those that will read and rely on this content daily.
- Gather users and find out how they use the current documentation. Then create a backlog of features that the users requested be included in the document.
- Prioritize and iterate.
In a recent exercise with a client, we discovered that the developers were the primary users of the technical documentation and only used it to perform the following tasks:
- Identify dependent applications and processes
- Understand the original intent of the application
After further investigation, we learned that neither of these tasks were easy to perform with the existing documentation. Additionally they had a list of other unmet needs:
- Discover the location of the project in source control
- Discover the location of key XSD files
- Easily access the documentation online
- For services, a listing of key methods
- For data sources, a data diagram
The implementation ended up being fairly simple. We divided the document into 3 sections:
- Data Model
In each section, we documented the name and the purpose of the application. To facilitate on-boarding of new developers, we documented the source control location. To aid with the assessment of impact of changes to the application we documented all external dependencies into and out of the application. For services, we documented the interface for using it. For databases we included a data diagram. For integrations, we documented relevant message formats. Whenever possible, we linked to existing documentation rather than recreating it.
Finally, the entire document was shared on their SharePoint site. There are discussions around migrating it to a WIKI in the future as well.
The technical documentation we produced was simple and included a number of clear advantages over the previous incarnation. This quickly became evident over the course of the project. The development team regularly updated the document and continues to use it today.