Documentation Shouldn't Be Used to Cover Technical Debt

In my previous post, I talked about documentation having technical debt.  Normally this debt is a burden on the users, and therefore the customer support team (this is one of the reasons why documentation has value, rather than just a cost, but I'll expand on the benefits of documentation in a future post).  But technical debt in the software, whilst potentially being a burden on customer support - and indeed customers - can become a big burden on documentation, and lead to more technical debt in the documentation itself.  Allow me to clarify. 

If your software:

• Does something when it shouldn't do;
• Doesn't do something when it should do;
• Does something in an unexpected way;
• Does something in an incorrect way;
• Is unnecessarily complicated;
• Is not designed with ease-of-use in mind;
• Causes an unnecessary manual intervention;
• Causes an unnecessary manual correction;
• Causes the user any problem that requires them to contact Customer Support;

Then your software has technical debt that should be explained in the documentation.  That's a whole bunch of known issues that have to be documented in at least one place, and maybe more (for example, on a dynamic customer-facing website and also in the release notes), as well as additional documentation effort required to talk the users through bad design or bad implementation.  This is a burden on the documentation team.  In a very real sense, development's debt is therefore documentation's debt, because we (are one of the teams that) have to pay the interest on that debt until it is paid in full by development.

On top of this, the additional documentation that has to be done has to be recorded and monitored, so that as the development team pay back their debt in code, we can amend our documentation to match.  As soon as this happens, there is a technical debt in the documentation, because it no longer matches the software.  This debt may only last until the writer has completed the documentation task that go with the development task, or, as happens more than it should, a developer might see and fix something whilst they are working on the code line but not mention it because they didn't realise it was documented anywhere, and the documentation debt never gets paid.

A simple example might be that the documentation states that a process may take some time if there is >= 10000 records.  A developer is working on fixing an unrelated issue in this process, and whilst she's in the code she realises that a minor change to a While loop will speed up the process significantly, especially for larger record sets.  She makes this change, as well as fixing the unrelated bug, documents the bug fix (but not the speed change), and moves on to the next task in the backlog.  Bang, your documentation is now incorrect, and there is no way you'll ever know about it.  Meanwhile, your customers "know" that this process is not as fast as it should be, and this decreases their satisfaction with your product.  This is a small error in your documentation, and the customer's satisfaction decrease is equally small, but if you multiply this by 10, or 20, or 50 small errors then their cumulative weight can make your documentation seem inaccurate and your product quality seem poor.


The other large burden that technical debt can place on documentation is when the software is unnecessarily complex.  A friend of mine once described a product he worked on as suffering "death by a thousand parameters", as every piece of additional functionality that a customer wanted was parameterised so that the other customers could continue using the product in their own way.  This led, as you can imagine, to a ridiculously complicated system, and was caused entirely by an unwillingness to say no to shouty customers, and an equal unwillingness to make long-term strategic decisions that would benefit the majority of customers instead of just the most obnoxious complainers.  The fate of this product was entirely obvious to all but those who's unwillingness led it to its inglorious endpoint.  This situation is a somewhat extreme example, and I suspect it's particularly prevalent in a Dirty Agile situation where the Product Owner is not the hawkish gatekeeper they should be, but it casts a light on a problem that writers face in many companies - the expectation that technical debt has been "dealt with" as long as someone has documented it.

I don't know how to say strongly enough that this is wrong, but maybe Scott Adams can help:

'Nuff said....

 







That kinda sums it up right there.  The scary thing is that some people need that explained to them, or they see the superficial humour but don't see it as a genuine problem that needs solving.  If as a writer you find yourself spending any significant time writing documentation to cover the technical debt of your software, then that software will be unlikely to provide you with a long term career.  No company with any pretensions to success will have that level of debt in their products, because they won't get the confidence of their customer base, and without that confidence they won't make the sales that will sustain the company in the long term.  On top of that, the cost of maintaining a product with significant technical debt is much higher than the cost of maintaining a product with low levels of technical debt, so you get the double whammy of low customer confidence leading to low sales income on the one hand, and high maintenance cost on the other.  Hopefully you don't need to be a business guru to work out the consequences of this....