Technical Debt Scenario #5: The code documents the system.

Unfortunately, several long-time developers have left the product team. In addition, there is virtually no technical documentation for the system. Even the architectural decisions are no longer traceable. What would you do to eliminate this kind of technical debt?

Technical Debt Scenario #5: The code documents the system.
Photo by Paul Hanaoka / Unsplash

Let us look at the fifth scenario, "The code documents the system." which shows how technical debt can arise.

If you are interested in the other four scenarios that show how technical debt can arise, click on the links below.๐Ÿ‘‡

Technical Debt Scenario #4: Hype Driven Development
The development team is always on the hunt for the latest technology hype. Currently, there are more than two front-end frameworks used for the product and the time to launch new features is getting longer and longer. What would you do?
Technical Debt Scenario #3: I donโ€™t care about the product.
The development team works too fast and breaks things. You find that they do not care about the product at all. What would you do about it? And how can you prevent the resulting technical debt?
Technical Debt Scenario #2: Feature factory
Your stakeholder wants to see features at an impossible speed. Your teamโ€™s velocity is dropping due to technical debt, so sometimes the product owner or another stakeholder says, โ€œI do not understand why itโ€™s taking so long to add a new feature.โ€ What do you say then?
Technical Debt Scenario #1: Starting without any architectural vision
The team is working on a new software product. The only thing the team wants is to start coding. How can technical debt already cause?

Table of contents


A new developer starts today. As an introduction, each team member gives him a brief introduction to a particular part of their software product.

Developer 1: Hey. I show you our frontend architecture. Let us get started...

Developer 1 opens the IDE.

Developer 1: Our frontend app is based on Angular. ย 

New Developer: Ah, okay. Cool. Why did you choose Angular?

Developer 1: Hm. I do not know, developers 2 and 3 chose it two years ago. They are no longer with the company. I do not know the reasons anymore.

Developer 1: Browses through the code...

Developer 1: Here you can see the structure of our modules. As you can see in the code, we try to structure our frontend by domains. So each business part gets its own Angular module, which is lazy loading.

New Developer: OK - What are the business domains of the application?

Developer 1: I work primarily in the payments area. But...I assume there are also the ordering, shipping, and referral domains. But I do not know much about those domains. You can roughly examine them in the code structure.

New Developer: Is there any documentation on the software architecture?

Developer 1: Yes. Wait, let me show you something from Confluence. We had a task to document it a year ago.

Developer 1 opens the documentation.

Developer 1: You can see the documentation here. But hmm... I think it's really out of date. You are probably better off going through the code ๐Ÿ˜€

What is the problem?

An often underestimated problem in software development is "technical" debt in documentation, also known as "documentation debt".

Essentially, I have experienced three problems in documenting technical systems:

๐Ÿ‘‰ Lack of documentation

Often I have heard "the code documents the system".

But can the code really document the system? I doubt it.

Ideally, you can learn something about the business domains in the code. But I do not see, for example, what technical choices were made and why.

  • Why is XYZ framework used?
  • Why is the system structured by layers?
  • What is the deployment view?
  • ...

๐Ÿ‘‰ Outdated documentation

Are the Confluence pages or PDF documents you show when introducing a new developer always up to date? I think no.

Often the documentation is outdated or no longer up to date when the system changes and becomes worthless.

๐Ÿ‘‰ A bunch of documentation, but not relevant

The art of technical documentation is to describe exactly as much as necessary - and no more.

I have seen teams document too much to meet certain organizational or procedural constraints (or other weird needs).

The documentation missed the core goals or only met the procedural requirements or was even rather obstructive to find the relevant parts, e.g. architectural decisions or non-functional requirements and their quality scenarios.

How can you prevent this problem?

If you don't have any technical documentation and need to know the relevant technical things about your system, start here.

A good template for architecture documentation is arc42 ๐Ÿ‘‡

All you ever need to construct, communicate and document your software architecture. Proven, practical and pragmatic. Free and open source, takes the pain out of documentation.

arc42 offers an excellent documentation approach for documenting and communicating software and system architectures.

The template promotes the following parts of the documentation:

  1. Requirements and Goals
  2. Constraints
  3. Scope & Context
  4. Solution Strategy
  5. Build Block View
  6. Runtime View
  7. Deployment View
  8. Crosscutting Concepts
  9. Architecture Decisions
  10. Quality Scenarios
  11. Risk & Technical Debt
  12. Glossary

You can think of each chapter as a drawer where you can put the appropriate pieces of documentation.

If you have no documentation at all, I would not start with a large and comprehensive documentation task in the backlog. That would be a bad example of starting with architecture documentation.

Instead, I would add the affected elements to the documentation step by step, for example during the development of a new feature or during a refactoring. This way, the documentation is continuously updated and stays current.

Hint: Gernot Starke gave a good talk on frugal documentation (in German).

Solve outdated documentation with documentation as code

One way to solve the problem of outdated documentation is to treat documentation like code, also known as "doc as code".

This means that you write the documentation using the same tools you use to write the code:

  • IDE
  • Version control (Git)
  • Plain text markup (like Markdown, Asciidoc)
  • Code reviews
  • Build system to build and deploy the documentation
  • Testing and extraction of metrics like 'readability'

Documentation as code encourages documentation maintenance, as you can work with your usual Git workflow and use pull requests to check documentation and block merging of new features if the request does not contain the (updated) documentation. This encourages developers to write documentation for these features as they develop them.

Supporting tools for documentation as code:

AsciiDoc Home Page
AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.
Open-source tool that uses simple textual descriptions to draw beautiful UML diagrams.
Easily create beautiful UML Diagrams from simple textual description. There are also numerous kind of available diagrams. Itโ€™s also possible to export images in PNG, LaTeX, EPS, SVG.
Architectural Decision Records
Homepage of the ADR GitHub organization
GitHub - docToolchain/docToolchain: a Gradle based AsciiDoc Toolchain for Software Architecture Documentation
a Gradle based AsciiDoc Toolchain for Software Architecture Documentation - GitHub - docToolchain/docToolchain: a Gradle based AsciiDoc Toolchain for Software Architecture Documentation

Refactor your current (outdated or irrelevant) documentation

As with refactoring code, you can do this with your current documentation. If you have a lot of outdated or partially irrelevant (or unused) documentation about your system, you can refactor your documentation using the arc42 template.

Suggestion for planning the refactoring of your documentation:

  • Start with architecture documentation based on the arc42 template, ideally using the documentation technology stack above (e.g. ascii doc) in your target git repository.
  • Set up a documentation CI-/CD-pipeline that creates and delivers the target representations of the documentation.
  • Identify the parts of the current documentation that are relevant according to the arc42 chapters.
  • For new features or changes, migrate the relevant old documentation directly into the new format.

After that, you have a new documentation basis for your technical documentation.


If you treat your documentation like code "documentation as code", you can address problems like this:

  • Outdated and irrelevant documentation because every pull request should include new or changed documentation.
  • Media breaks and documentation fatigue because the developer can write documentation directly using the tools and methodology for writing code.

arc42 provides a solid template for refactoring your existing documentation.

documentation as code combined with the arc42 template is a future-proof and motivates the development team to write sustainable and traceable technical documentation.

Start now - and get proper technical documentation for your system.