The “triple threat” part three: Documentation

We’re looking at what we at Foxsoft call the “triple threat” to mission-critical and other software and apps: lack of maintenance, technical debt and, here, lack of documentation.

I’ve spoken about documentation before, specifically within the context of Living Documentation, so I’m not going to spend too much time here repeating myself.

I will however talk about the unfortunate reality of documentation: it’s often treated as an afterthought. Documentation is the thing which gets skipped due to looming deadlines and other pressures; the thing which developers try to avoid doing, using the excuse of the Agile Manifesto’s preference for “working software over documentation”.

Even when a development team takes a documentation-first approach (as we do at Foxsoft), it’s possible to miss important information, or to assume too much knowledge on the part of the recipient.

It’s also worth acknowledging that writing documentation is hard. Any sort of writing is hard, and if it wasn’t for my editor, these blog posts would be in a far worse state (thank you, Liz). But developers writing documentation don’t get the benefits of a professional editor.

And so, it is because of these and many more reasons, that we specifically target missing and incomplete Documentation as our third threat. It is vital to spend time specifically and explicitly filling in the gaps and making the improvements to the documentation that are required, otherwise it threatens the integrity of your software or apps and can lead to mission-critical failures.

Summary

To end this series of posts, I want to share a proverb which I think provides a nice summary of the reason tackling the triple threat is important.

For want of a nail the shoe was lost.
For want of a shoe the horse was lost.
For want of a horse the rider was lost.
For want of a rider the message was lost.
For want of a message the battle was lost.
For want of a battle the kingdom was lost.
And all for the want of a horseshoe nail.