Technical Debt Scenario #5: The code documents the system.
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.👇
Table of contents
Scenario
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 👇
arc42 offers an excellent documentation approach for documenting and communicating software and system architectures.
The template promotes the following parts of the documentation:
- Requirements and Goals
- Constraints
- Scope & Context
- Solution Strategy
- Build Block View
- Runtime View
- Deployment View
- Crosscutting Concepts
- Architecture Decisions
- Quality Scenarios
- Risk & Technical Debt
- 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:
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.
Summary
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.