Thursday, 9 April 2015

Documentation has Technical Debt Too

"Technical debt" is a concept in programming that describes all of the work that has to be done later because it wasn't done (or done right) at the time.  Wikipedia sums it up nicely:

"The debt can be thought of as work that needs to be done before a particular job can be considered complete. If the debt is not repaid, then it will keep on accumulating interest, making it hard to implement changes later on. Unaddressed technical debt increases software entropy [software complexity]."

A solid overview of technical debt in software projects can be found here.  That link details the technical debt experienced within the code line, which is the common understanding of where such debt accumulates.

However, the following issues are also a form of technical debt for your documentation:

  • A backlog of documentation tasks (where documentation is not in your definition of done).
  • Known errors in your documentation.
  • Known omissions in your documentation.
  • Known ambiguities in your documentation.
  • An out-of-date Table of Contents or index.
  • A lack of consistent terminology and/or use of standards within a document.
  • A lack of consistent terminology and/or use of standards within a documentation suite.
  • A lack of consistent terminology and/or use of standards across different documentation suites.
  • Documentation that is out of sync with the most recent release.
  • Missing documentation (e.g. you have installation notes but no configuration guide).
  • Multiple documents that could (and therefore should) be single sourced.

There are other types of technical debt for documentation; these points should be thought of as examples, rather than as an exhaustive list. As all technical debt is shared by the whole team, our debt is their debt and vice versa. I'm sure you can imagine that there is some contention about whether documentation is included in the "official" definition of technical debt, but that
largely boils down to whether or not documentation is included in the Definition of Done, which I've discussed elsewhere.

The important point is that, like a software application, a large piece of documentation can be very complex, and the more errors or omissions there are, and the earlier these occur, the more you pay for them when trying to fix the errors or include the omissions at a later date.  There is no magic bullet for fixing technical debt, so I won't try to provide one here, but at a later date I will be posting about the value of documentation, and hopefully that will give you some ideas about how to persuade people of the importance of getting your documentation correct, consistent and complete.


That aside, don't be afraid to talk in terms of technical debt if you need to persuade your Product Owner to prioritise tasks that will fix these problems.  The more that your documentation issues are seen as being similar in scope and type to the software issues, the more likely you are to be supported when you ask for a higher priority to fix your technical debt.  It's important to frame requests in language that your development-oriented team mates can understand, and most developers understand both the importance of minimising technical debt, and the frustration that having it causes.