Documentation

How to write a truly good technical documentation?

Learn how to write effective technical documentation that is clear, useful and maintainable, avoiding technical debt and costly mistakes.

Does writing high-quality documentation require too much work? Think about it. Have you encountered more good or bad technical documentation in your career?

In many cases, documentation is missing, outdated, scattered or misplaced. The result is wasted time, lost knowledge and lost of credibility. Yet, technical documentation is essential. It captures technical decisions, security rules and architectural choices serving as a historical reference for audits, verifications and future evolutions of the system.

Why is technical documentation often poorly done?

Writing useful, actionable documentation takes time, focus and discipline. Unfortunately, this crucial work is not always valued by management. Developers, under pressure to deliver, often settle for quick personal notes or minimal compliance with a “quality checklist.” As a result, documentation is created haphazardly, incomplete, scattered in some forgotten wiki or limited to vague comments on two functions before moving on to something else.

That’s how technical debt begins with time losses, security risks and soaring maintenance costs.

"Technical debt linked to poor documentation" Caption: Technical Debt: From Metaphor to Theory and Practice, By Philippe Kruchten, Robert Nord, and Ipek Ozkaya

What makes “good” technical documentation?

Technical documentation is a human language, written by humans for humans, with its own lifecycle and changing teams. When you write it, assume that the next team to maintain your project has no context, no background and no prior knowledge. Writing good documentation requires empathy.

Good documentation should:

• Help onboard new developers quickly.
• Explain the rationale behind technical decisions.
• Enable smooth maintenance without endless investigations.
• Avoid drowning the essentials in unnecessary details.

What are the essential criteria and contents of technical documentation?

To be effective, documentation must strike the right balance of information (not too much, not too little). Three criteria are non-negotiable:

• It must actually exist. This may sound obvious but in reality, many “technical docs” exist only on paper (or in a forgotten repo), outdated, incomplete or untested. In other words: they don’t really exist.
• It must be easy to find. A new developer or admin shouldn’t spend an hour looking for it.
• It must be understandable in seconds. Anyone should quickly grasp the goal, the context and the next steps.

A solid documentation set should include at least:

• A global overview (architecture, modules, key decisions).
• Basic instructions (installation, build, tests, deployment).
• Justifications for technical choices (why certain modules, microservices or architectures were chosen).

Above all, documentation must stay up to date. An outdated document is worse than no document at all.

Where should technical documentation live?

Documentation should be concise, structured in layers, from the closest to the code to the most global. It can and should live in several places:

• Within the code itself: through comments that allow the author to recall their reasoning years later and that help others understand it.
• Component level README: describing constraints, features and design decisions for each component. When appropriate, link it directly from the code comments.
• Project level README: the main entry point: readable, versioned, visible and accessible. It can include a clickable table of contents pointing to a wiki or other resources. Alongside it, a CONTRIBUTING.md file should describe contribution guidelines, scripts and deployment processes.

For more complex systems, a wiki can complement the code level docs with broader explanations of architecture or high-level concepts.

In short: documentation should live where developers live.

AI and technical documentation: limits and exceptions

There are a few valid use cases for AI assisted documentation but overall, we strongly advise against using AI to write technical documentation.

The limits of AI in documentation

In some highly specialized fields like medicine, AI tools trained on validated datasets with strict quality control and traceability can safely support human work. But this context is worlds apart from a developer using a general purpose AI like GitHub, Copilot or Codex to write or generate documentation.

These tools introduce several issues:

• Opaque sources, questionable quality: Copilot or Codex generate text from massive datasets with unknown provenance. There’s no guarantee that the content is accurate, complete or even legally safe.
• Inaccuracies and nonsense: without enough context, AI may fabricate information or introduce subtle errors. And the more context you provide, the more internal data you expose.
• No accountability: unlike versioned frameworks or libraries, an AI provides no changelog, no traceability. You can’t audit why it produced a given paragraph.
• Confusing “plausible” with “true”: AI generated text sounds credible but may contain dangerous oversimplifications. Misleading documentation is worse than missing documentation.
• Data leakage risks: sending internal code or data to external AI tools exposes your intellectual property. Even if vendors claim privacy, you lose control once your data leaves your systems.
• Intellectual property issues: AI output may reuse licensed code snippets from public repositories. If reused commercially, you are liable. Security researchers can easily trace such patterns.
• Confidentiality breaches: uploading your production codebase to an online AI model is reckless. You may as well hand your industrial secrets to a public LLM’s server logs.

Remember: technical documentation is a human-to-human communication tool. Using Copilot or Codex to write it means outsourcing your project’s critical memory to a black box you neither control nor understand.

When AI can (sometimes) help

Documentation must remain human work, but AI can have limited, supporting roles in very specific cases:

• Automatically generating function comments.
• Producing basic documentation templates.
• Using an AI enhanced IDE (like Cursor) to absorb project context.

Even in these cases, a human review is mandatory. This is a non-negotiable rule because one click, one merge request and your credibility could take a serious hit.

Best practices for writing solid technical documentation

The goal isn’t to write an encyclopedia. It’s to build lightweight, useful and up to date documentation.

Integrate documentation from the start

Documentation is not an end of cycle task. It should evolve alongside the code, in maintainable formats (Markdown, HTML, Wiki).

Write clear, meaningful code comments

Explain what seems obvious to you now but won’t be obvious to others later. Clarity beats verbosity.

Version and review documentation

Keep docs in the same repository. Review them with each pull request. Any new feature must come with updated documentation. Use Git or similar tools to track history, context and rationale behind changes.

Assign ownership and rely on standards

Give documentation responsibility to a team member (someone accountable for maintaining a clear history, version archive, and regulatory justification if needed). You can use proven frameworks to ensure structure and longevity:

• C4 Model – for hierarchical architecture visualization.
• Arc42 – for modular system architecture documentation.
• UML – for standardized design diagrams.
• ISO/IEC 42010 – for standardized architecture descriptions.

Conclusion

Technical documentation is not an administrative burden but a strategic asset. It must be written for others, placed where it belongs and maintained with rigor. Anything else is just technical debt waiting to happen.