Imagine this situation. A new developer joins a project that has been under development for three years. First day — they get access to a repository with 400 thousand lines of code. The README.md says “run npm install, then npm start”. No architecture description. No explanation of why the system consists of 14 microservices. No information about which service handles authorization and which handles billing.
A week passes. The new developer still can’t set up the local environment independently because the configuration requires secret knowledge about environment variables, whose names only one senior knows. After a month, they finally start being productive. A month of onboarding instead of three days. The cost? The developer’s salary for three unproductive weeks, time of seniors answering questions, frustration on both sides.
This story repeats itself in thousands of IT teams. This article is a practical guide to technical documentation — specific types of documents, tools, processes and anti-patterns that will help your team create documentation that is actually useful.
Quick Summary
What you’ll learn from the article:
- Why lack of technical documentation costs the company significantly more than creating it — and how to estimate this cost in hours and money.
- What types of technical documentation exist (architecture, API, runbooks, ADRs, onboarding guides) and when each of them is essential.
- What the docs-as-code approach is and why treating documentation like source code changes the quality of the game.
- Which tools to choose — Confluence, Notion, MkDocs, Swagger/OpenAPI — with a comparison of advantages and limitations.
- How to keep documentation alive in agile methodologies, who should own it and what anti-patterns sabotage even the best intentions.
Why Technical Documentation Matters — The Costs of Its Absence
Many IT teams treat documentation as a luxury — “nice to have, but not now, because we have a sprint to close”. This is short-sightedness that generates costs visible only when it’s too late.
Onboarding cost. Research by Stripe (Developer Coefficient Report) indicates that developers waste an average of 17.3 hours per week on unproductive activities — a significant portion of which is searching for information about the system and reconstructing knowledge that could have been documented. If onboarding a new developer takes a month instead of a week, the company loses 3 weeks of productivity for each new person.
Bus factor cost. When a key developer leaves and takes knowledge with them, the team is left with a system that no one fully understands. In extreme cases, companies decide to rewrite modules from scratch because understanding the existing code without architectural context is more expensive than a new implementation.
Cost of production bugs. Lack of runbooks means that a production incident at night turns into panic. The on-call engineer doesn’t know how to restart the service, what dependencies the system has or what metrics to monitor. Recovery time increases because each step requires exploration instead of following instructions.
Communication cost. Well-documented APIs eliminate dozens of daily messages like “how to call endpoint X?” or “what parameters does method Y accept?”. Documentation is asynchronous communication — instead of interrupting a senior’s work with a question, the developer checks the documentation.
Types of Technical Documentation
Technical documentation is not a monolith. Different documents serve different purposes and have different audiences. Understanding these types allows you to build documentation strategically — instead of “documenting everything”, you document what brings the greatest value. It’s worth combining this topic with BPMN process modeling, which provides formal tools for visualizing flows in organizations.
Architecture documentation explains how the system is built at a high level — components, relationships, data flow, architectural patterns. It contains component diagrams (e.g. C4 model), technical decisions and their justification. This is the type whose absence is felt most strongly — a developer sees the code but doesn’t understand why it is as it is and not otherwise.
API documentation describes how to communicate with the system programmatically — endpoints, parameters, data formats, response codes, authentication. The OpenAPI standard (formerly Swagger) has become the de facto norm for REST APIs and allows automatic generation of documentation from code.
Runbooks are step-by-step instructions for typical operations — deployment, service restart, incident handling, database migrations. Their value is revealed under stress: when production is down, no one is able to rationally analyze code — they need simple steps: “do A, check B, if C then do D”.
Architecture Decision Records (ADRs) document key architectural decisions — what we decided, why, what alternatives we considered. They solve the classic problem “why is this so?” — a developer reads an ADR and understands the context of the decision, even if the people who made it left long ago.
Onboarding guides lead a new team member through environment setup, system architecture and team processes. This is an investment that pays off with each new person on the team — well written, it shortens productive time from weeks to days.
| Documentation type | Main audience | Update frequency | Priority | Typical format |
|---|---|---|---|---|
| Architecture | Developers, architects | Quarterly or upon changes | High | Markdown + C4/UML diagrams |
| API | Integrating developers | With every endpoint change | High | OpenAPI/Swagger |
| Runbooks | DevOps, SRE, on-call | After each incident | High | Markdown, wiki |
| ADR | Entire technical team | When making decisions | Medium | Markdown in repository |
| Onboarding guide | New team members | Quarterly | Medium | Markdown, wiki |
The Docs-as-Code Approach
Docs-as-code is an approach where documentation is created and managed the same way as source code. Instead of keeping documentation in a separate system (Confluence, Google Docs), you keep it next to the code — in the same repository, in text format (Markdown, AsciiDoc).
Key principles of this approach are: versioning through Git (full change history, possibility of rollback), review in pull requests (documentation changes go through code review just like code), automatic building (tools like MkDocs build professional HTML pages from Markdown) and linting and validation (automatic checking of links, formatting, required sections).
Why does it work better than wikis? Wikis have a fundamental problem — documentation lives separately from code. When a developer changes an API, they must remember to separately update the wiki. And people forget. Over time, the wiki becomes a graveyard of outdated information. Docs-as-code solves this: changing code and documentation in one pull request means the reviewer can require documentation updates as a condition of merge.
Tools for Technical Documentation
The choice of tool depends on context — team size, organizational culture and types of documentation you create. Many teams combine several tools: MkDocs for technical documentation in the repository, Confluence or Notion for process documentation, Swagger/OpenAPI for APIs.
| Criterion | Confluence | Notion | MkDocs | Swagger/OpenAPI |
|---|---|---|---|---|
| Approach | Wiki (SaaS) | Wiki + database (SaaS) | Docs-as-code (static pages) | API specification |
| Git integration | Weak | None | Native | Good (YAML in repo) |
| Visual editing | Yes (WYSIWYG) | Yes (block-based) | No (Markdown) | No (YAML/JSON) |
| Versioning | Primitive | Primitive | Full (Git) | Full (Git) |
| Entry barrier | Low | Low | Medium | Medium |
| Cost | Paid ($5-10/user/mo.) | Freemium ($8-10/user/mo.) | Free (open source) | Free (open source) |
| Best use case | Process documentation | Company wiki, onboarding | Technical documentation | API documentation |
| Desynchronization risk | High | High | Low | Low |
Documentation in Agile Methodologies — Living Documents
The Agile Manifesto says: “working software over comprehensive documentation”. But this doesn’t mean “zero documentation” — it means: don’t create documents that no one will read, just because the process requires it.
The concept of living documentation assumes that documentation is part of the system and updates together with code. Examples: OpenAPI spec generated automatically from code (in FastAPI or NestJS), diagrams defined in text by Mermaid or PlantUML (versioning and diff like with code), BDD tests (Given/When/Then) as executable specification of system behavior.
The most effective way to maintain documentation in agile: include it in the Definition of Done. New API endpoint — updated OpenAPI spec. Architecture change — updated diagram plus new ADR. New service — onboarding guide and runbook. Not every ticket requires documentation, but changes affecting architecture, API or operations — yes.
Technical documentation can also be a tool for process optimization in organizations. When deployment processes, incident handling or onboarding are described, it’s easier to analyze them, find bottlenecks and improve them.
Maintaining Documentation — Ownership and Review Cycles
Writing documentation is 20% of the effort. Keeping it up to date is 80%. Documentation that no one updates becomes not only useless over time, but even harmful — it misleads.
Ownership — each document has an owner. A document without an owner is doomed to degradation. Architecture documentation — Tech Lead. Runbooks — DevOps/SRE team. ADRs — person making the decision. Onboarding guide — last person who went through onboarding (because they know best what is outdated). Add “Owner” and “Last reviewed” fields to document metadata.
Review cycles. Set regular reviews: critical documentation (runbooks, onboarding) quarterly, architecture once every six months or after each major change, API docs automatically up to date if generated from code. 30 minutes quarterly is an investment that prevents hours of frustration.
Timeliness signaling. Give the reader a signal whether documentation is current: date of last update visible on the page, warning banners for old documents, automatic check in CI/CD marking documents not updated longer than a defined threshold.
Documentation Anti-Patterns — What to Avoid
Even teams aware of the value of documentation make mistakes. Here are the six most common anti-patterns:
“We’ll write documentation after the project is finished.” A project never “finishes” — after deployment there are fixes, after fixes new features. The moment “now we’ll write” never comes. Solution: documentation created incrementally, together with code, in the sprint.
“Write-only” documentation. Someone writes 50 pages of architecture description. No one reads it because the document is too long and academic. Solution: write for a specific audience and scenario — not “system description”, but “how to add a new endpoint to the Orders service”.
Documentation duplicating code. Comments like “increment counter by 1” above the line counter += 1. Code says “what” — documentation should say “why”.
Wiki-labyrinth without structure. Three pages on the same topic, none complete, none current. Solution: establish structure upfront, have one page per topic, use redirects instead of duplication.
Paralyzing perfectionism. “I won’t write it because I don’t have time to write it properly” — and there’s no documentation at all. A rough draft of a runbook with 5 steps is infinitely better than no runbook.
Lack of documentation culture. One developer writes, the rest don’t. Solution: documentation must be part of team culture — requirement in Definition of Done, praise for good documentation, templates making creation easier, lead setting an example.
How EITT Supports Teams in Building Documentation Culture
Technical documentation is not just a matter of tools — it’s a matter of team competencies and habits. EITT has been helping IT teams build skills not only in technologies, but in engineering practices that improve work quality for years.
In our offer you’ll find training covering workshops on technical writing for development teams, practical configuration of the docs-as-code approach (MkDocs, CI/CD integration), training in agile and DevOps including building Definition of Done with documentation, and workshops on Architecture Decision Records and the C4 model.
We base our work on the experience of over 500 experts conducting over 2500 trainings, with an average participant rating of 4.8/5. Our programs combine theory with practice — participants leave training with ready-made templates, configured tools and an implementation plan.
Summary
Technical documentation in IT projects is an engineering tool that reduces onboarding costs, decreases bus factor, accelerates incident resolution and eliminates repetitive questions. Start with three things: onboarding guide (so new people quickly become productive), runbooks (so incidents don’t turn into chaos) and ADRs (so architectural decisions survive longer than one developer’s memory). Keep documentation in the code repository, include it in the Definition of Done and assign document owners. Don’t postpone it “for later” — because “later” never comes.
Develop Your Skills
This article is related to the training Agile project management with Kanban and Jira - a practical approach. Check the program and sign up to develop your skills with EITT experts.
Read also
Frequently Asked Questions
What types of technical documentation should every IT team maintain?
Every IT team should prioritize at least three types: onboarding guides so new members become productive quickly, runbooks so incidents don’t turn into chaos, and Architecture Decision Records (ADRs) so design rationale survives longer than any individual developer’s memory. API documentation and architecture documentation are also highly valuable, especially for teams building distributed systems or collaborating with external integrators.
What is the docs-as-code approach and why is it better than wikis?
Docs-as-code means managing documentation the same way as source code — storing it in the repository alongside code, versioning it through Git, reviewing changes in pull requests, and building HTML pages automatically from Markdown files. This approach solves the fundamental wiki problem of documentation living separately from code, which leads to outdated content when developers forget to update the wiki after code changes.
How can teams keep documentation up to date in agile environments?
The most effective strategy is to include documentation in the Definition of Done for relevant tickets. New API endpoint means updated OpenAPI spec, architecture change means updated diagram plus a new ADR, and new service means an onboarding guide and runbook. Assigning document owners and scheduling quarterly reviews for critical documentation also prevents gradual decay.
What is the biggest anti-pattern in technical documentation?
The most damaging anti-pattern is postponing documentation “until after the project is finished” — because in practice that moment never arrives. Projects continuously evolve with fixes and new features, so the documentation backlog only grows. The solution is creating documentation incrementally alongside code within each sprint, even if initial drafts are rough and imperfect.