The Most Important Thing Nobody Wants to Write

Documenting software is the software developer equivalent to washing your windows.

Ask any developer how they feel about documentation, and you usually get a sigh, a grimace, or possibly a vague promise that they’ll “get to it later.” Unfortunately, just like windows, later means, harder, more work and in the worst-case scenario, a complete renovation. When “later” turns into “never”, organizations pay the price with onboarding delays, security gaps, and in some infamous cases — catastrophic project failures.

As most IT pros know, October is Cybersecurity Awareness Month. With attacks on the rise and budgets shrinking a look at the 5Ws of documentation and how it impacts your cybersecurity efforts is another way to ensure your windows are clean.

Documentation isn’t glamorous or sexy or a task that fuels creative genius and it won’t get applause at the next all-hands. But it is the invisible scaffolding that keeps your software maintainable, your systems secure, and your legacy platforms from collapsing into chaos.

Why Documentation Deserves More Respect

• It’s Your Memory in Writing
  Developers move on, humans forget, and institutional knowledge evaporates. Documentation preserves the rationale behind design choices, logic, processes and prevents systems from turning into black boxes. Ask yourself this, “Six months from now, will your best engineers remember why that obscure function returns null under certain conditions?”
• It Scales Knowledge
  Onboarding a new engineer shouldn’t require a guided tour from the one person who “knows everything”. With solid up to date documentation, new hires become productive in days, not weeks. Without it, you’re running an apprenticeship program, not a software development team.
• It Reduces Single Points of Failure
  Every organization has that one person who “just knows how it works”. That’s great until they resign, retire, shift to another project, or perish the thought … go on a 2-week vacation. Documentation gives you the opportunity to share a wealth of knowledge efficiently, so you’re not dependent on a single human library.
• It Future-Proofs Your Software
  In many programs the code change is constant, and it should be, code is a living organism. Documentation explains why changes were and made future developers depend on it. Mull over this possibility: A bug is present in an API that works. Unknowingly a developer tries to update the code and without following documentation and they accidentally undo important logic or fix a bug in the library that applications depended on, creating an unintended undocumented feature, or worse breaking the whole system. Joel on Software discussed this back in 2004, because even back then documentation was important.

Who Should Be Writing Documentation?

In the words of John C. Maxwell: “Teamwork makes the dreamwork.”

Writing documentation is a team sport and each player’s role is different:

• Developers/Engineers should be documenting what and how: code comments, APIs, architectural diagrams.
• Product owners/business analysts capture the why: the business logic, customer needs, and regulatory requirements that shape the intersection between the aspirations of the organization, the user experience, and the business needs.
• Security teams should maintain threat models, access controls, and incident response plans (when).
• Operations/DevOps document the practical: deployment steps, monitoring protocols, and recovery runbooks (5Ws and H).

Documentation isn’t busywork meant for times when there are project lulls, it’s collective risk management and an ongoing necessity.

Why: The Cybersecurity Connection

Poor documentation is a vulnerability. Full stop!

• Unseen attack surfaces: If integrations aren’t documented, you don’t know where your system is exposed. Last week in our blog “Questions from the C-Suite” we talked about how hackers love an unchecked endpoint. A lack of documentation on endpoints that nobody remembers existing is a cybercriminal’s invitation to the party; documentation rescinds their invitation.
• Unpatched legacy software: We’ve talked a lot about legacy systems this year, because they are everywhere and one of their critical points of failure is the absence of thorough documentation. Outdated components and legacy platforms increase vulnerability to cyberthreats, without proper documentation the opportunity for exploitation remains. Documenting these systems must be part of your strategic tech debt management plan.
• Incident response chaos: During a breach, clear documentation allows your team to act quickly and effectively. Without it, they scramble for passwords, diagrams, and change logs while attackers move freely. The Oldsmar, Florida water treatment attack in 2021 illustrates this perfectly: outdated Windows 7 machines, undocumented remote access, and weak network segmentation nearly led to poisoned water supplies.

Where Documentation Is Critical: Legacy Systems

Legacy platforms are where it matters most. According to Gartner in 2023, approximately 65% of enterprise applications can be considered a legacy system.

We’ve said it before, but these systems:

• Run mission-critical functions.
• Were built decades ago, many by developers who have moved on.
• Have been patched repeatedly without clear records.
• Have integrations that keep breaking.
• Frustrate teams and users.

Without documentation, modernization is a gamble. You risk breaking vital integrations, losing data, fueling innovation drag or re-creating technical debt in newer frameworks.

Consider the FBI’s Virtual Case File project where the bureau spent roughly $170 million with the intentions of replacing its aging case management system. A contributing factor leading to its “failure to launch” was poor documentation of existing processes and shifting requirements. Imagine the public impact if the project was not abandoned before take off.

Documentation isn’t just about keeping legacy systems alive; it’s about equipping your organization with the knowledge necessary to eventually retire them safely, within budget.

When Documentation Fails: Case Studies

• Therac-25 Radiation Therapy Machine (1980s)
  Software errors caused patients to receive lethal overdoses of radiation. A contributing factor: error codes like “MALFUNCTION 54” had no documentation explaining their meaning, so operators kept restarting the machine. Hardware was continuously blamed but the lack of “inaccurate record keeping” and incomplete testing was ultimately the cause of these deadly failures (Leveson & Turner, 1993).
• Knight Capital Trading Glitch (2012)
  In 45 minutes, a misconfigured deployment script cost $440 million plus an additional $12 million in SEC fines. One of these fines was specifically related to documentation: “Did not have sufficient controls and written procedures to guide employee responses to significant technological and compliance incidents.”
• FBI Virtual Case File (2000s)
  As mentioned above, poor documentation left the agency unable to modernize, turning one of the most high-profile IT projects of its time into an expensive lesson in neglect.

Software documentation should be a living document. Keeping open tickets in your project management system for all software projects is an effective way for “creatures of habit” to have a place to log their documentation related time.

How: Documentation Best Practices

• Make it part of “done”
  A feature isn’t complete until documentation is updated. Additionally, a bug cannot be considered resolved if the fix is not in the documentation. If you are not documenting, you’re publishing code without context.
• Automate where possible
  Generate API docs, dependency graphs, and diagrams automatically; Swagger is an incredibly helpful tool for this. Machines handle consistency better than humans; they also don’t need liters of caffeine to maintain their focus on mundane tasks.
• Focus on the “why”
  Code shows what the system does. Documentation should explain why it was built that way. Architecture Decision Records (ADRs) are excellent for this and the link we provided has a series of templates to help you get started.
• Keep it alive
  Wikis, internal portals, and version-controlled docs beat static PDFs. Documentation should evolve and coexist with the life of the system/project. If it has been dormant for a while, resuscitation may be necessary.
• Review documentation like code
  Pull requests should have correlated updated docs as well as code. If new engineers can’t follow them, they’re not documentation — they’re decoration.

Conclusion

Documentation is rarely exciting, but it is vital, your code depends on it. It preserves institutional knowledge, distributes critical expertise, strengthens security, and keeps legacy systems from becoming a black hole of unmanageable risk.

Neglecting documentation has led to billion-dollar errors, failed modernization efforts, burgeoning levels of tech debt and unnecessary loss of life. Maintaining it is low hanging fruit for your team, it pays off with team resilience, corporate compliance, and peace of mind.

So, when someone asks, “Do we really need to document this?” the answer is simple: “Yes, because it’s cheaper than explaining to the board why the system failed and killed the annual budget.”