Bad Documentation is Technical Debt — Here's How You Solve It

Here's a puzzle for you.

Developers and C-level executives alike will tell you how important code documentation is. Why, then, is it so rare?

You'll find plenty of blame games on the internet about how developers with god complexes are to blame, refusing to believe their perfect code even needs documenting. Or, wait, perhaps it's all because of those greedy suits who care about nothing but profit?

Personally, I find it more interesting (and productive) to examine this from the perspective of the inherent disconnect between the two groups instead - specifically, a difference in opinion over what constitutes business value - and how we can bridge that divide.

💡 For certain examples, I'm going to use Swimm - a documentation tool that lets engineering teams easily create high-quality, code-coupled docs that are always up to date, and part of the IDE experience itself. It deftly cuts through many of these pain points so I'd recommend it, but honestly, the advice here is just as applicable, regardless of which solution you use.

The Disconnect Between Developers and Executives

Businesses exist to provide as much return on investment for stakeholders as possible. This inevitably means that any work done within the organization will be broadly divided into two categories:

1. Tasks that lead to new, exciting features for customers;
2. Overhead.

No prizes for guessing that within this narrow definition, documentation is always going to be classified as overhead - a second class citizen. Something that needs to be there for QC and compliance requirements, but work that is not visible to the customer, and thus not "real" value.

And businesses will always want to reduce overhead so that the majority of shareholder investment is spent on work that adds "real" value. After all, you can't ship a product without code, but you can ship one without any documentation.

Is this fair? No, of course not. Any developer worth their salt could tell you that this is how orgs accumulate tech debt. But businesses are not structured to respond to "doing it the right way" calls-to-action. They either need to move blazingly fast to be competitive (and have the necessary risk appetite), or are big enough that tech debt would likely not matter until a merger is on the cards.

Unless there's a complete shift, overnight, in how businesses do things, documentation will always be considered organizational overhead - even if that overhead means you eventually deliver more value for the same time worked. Short term gains are always preferred over long term investment.

How can developers stave off tech debt, then, if highlighting the benefits of having good documentation is just not enough as far as the money is concerned?

Re-Contextualize To Bridge The Divide

Let's examine this from the perspective of management, for a minute.

Technical documentation adds immense value for employees, but is usually a pure cost center for the organization.

1. Documentation doesn't make the company money. Its benefits - "Time saved", "Pitfalls preemptively avoided", "Knowledge hand-offs successfully completed" - are not quantifiable metrics, and don't show up on a balance sheet.
2. You can always make documentation better with more effort (hiring a dedicated technical writer, for example), so there's no theoretical ceiling on its cost. Companies that can justify this to the suits usually only operate at the scale of Amazon, Apple, or Cisco.

So if short-term gains are what drive the perception of value here, one solution that both sides could agree on is to re-contextualize the issue in terms of the high-probability, near-term risks of bad documentation - and how good documentation can solve these.

1. Reduced Effective "Bus Factor"

The Problem

The "bus factor" is a measurement of the risk resulting from information and capabilities not being shared among team members, expressed as, "how many mission-critical people can we afford to lose (by being hit by the hypothetical bus, or truck) before it threatens organizational continuity?".

In simpler terms: Components that work well, but are undocumented black boxes, are ticking time bombs. You absolutely need to document knowledge - you database schemas, your high-level architectural overviews, the working of your internal APIs - to be able to keep going in case critical team members are (temporarily or permanently) absent.

The Solution

No matter what you do, do not let knowledge become tribal. Canonize collective knowledge into official documentation whenever possible, so none of it is lost due to employee turnover.

You will run a healthier team with fewer points of failure if knowledge is freely shared instead of siloed. If you're using Swimm - a good way to do this is with Playlists that make the process of employee offboarding easy, and intuitive, making sure no ephemeral knowledge is ever lost.

Also, change your Definition Of Done to include documentation, and also a successful deployment of your project by an independent team, without any further input from the original developers. That's the acid test for your documentation.

2. Reduced Agility

The Problem

Ever wonder how these hot new startups can compete with FAANG over features? It's because they can be far more agile.

But I personally feel that when the Agile Manifesto became popular, most decision makers took home the entirely wrong lessons (re: documentation) from it.

Comprehensively documenting your code (to the extent of the gigantic, impenetrable manuals published by IT companies in the 70s and 80s) is definitely something that cannot be done in modern software development, but nowhere does it say you shouldn't make documentation a priority at all.

Without effective documentation that gives your devs the help they need, when they need it, you're going to end up mired in longer waits until new hires become effective, and you won't be able to respond to needs rapidly, be on the ball regarding staffing changes, or outsource any of your work effectively. You'd be the opposite of agile.

The Solution

Be aware of how you're documenting things. Design Docs aren't going to let your new people become useful faster, and Swagger specs aren't going to help them troubleshoot common issues or preemptively know the gotchas. The hidden cost of this? Having your experienced devs tied up in onboarding and training, instead of working on new features. It all adds up.

Swimm can remedy this with its concept of Walkthrough Documentation, which fills the role of the mentor walking you through the code, step by step, easing you into the workflow. An enhanced, curated version of a FAQ.

3. Higher Cost-to-Read-Code

The Problem

If you don't have a culture of documentation, your docs are going to be rushed afterthoughts. These docs often turn into wasted effort - because the cost to read them is way too high for a variety of reasons.

• They're the wrong kind of docs for the task a developer is trying to accomplish,
• They do not reflect the current state of the codebase, or
• They're scattered in various places, hard to find, and your readers are not going to bother sinking hours into the effort if they don't know whether there even is an answer to the problem hidden inside.

It's difficult to write documentation that lowers this cost, because it's difficult to figure out what's most important about the system you're in charge of, and how best to present that information. "Just write clean code!" is not going to do much good.

Plus, without a system in place, documentation that is decoupled from your code is like the proverbial tree in the forest. If it falls, is anyone ever going to hear it?

The Solution

The easiest solution here is to adopt a Docs-as-Code philosophy - your docs need to be created alongside the code and stored alongside the code, so it all stays in sync. If you're using Swimm, this becomes easy because you can directly refer to code tokens and snippets within markdown docs, which are always kept Auto-synced with your GitHub code.

The Docs-as-Code approach makes it easy to create highly readable, highly available documentation at whatever granularity that is needed.

Summary

In the context of businesses, documentation is organizational overhead. There's no way around that. The best way to solve it is to understand the other perspective you're trying to communicate with, and find common ground. You need to meet the organization where it's at, not where you want it to be.

I don't think that's an unreasonable ask - after all, consistent value generation is driven by processes that can be explained clearly and reliably to employees. Surely both sides can see that.

And using a tool like Swimm to demonstrate the growth potential that good documentation brings to an organization, could be a fast way to get there.