# Self-Documentation

**In short:** Self-documentation means a system carries the information needed to understand it inside itself, mainly in its code. This cuts separate documents that fall out of date, but it cannot capture reasons or the full picture.

## Explanation

Self-documentation means the code and its structure explain themselves. Readers should not need a separate document to understand a building block.

**Why it matters.** Missing or outdated documentation is a typical failure. A separate document must be updated by hand, so it is easy to forget. Documentation that stays up to date with little effort avoids this problem.

**Code as the main source.** Code is the only artifact detailed and precise enough to be the primary documentation. It is not the only documentation, though. It is also not automatically good documentation. Like any documentation, it can be clear or gibberish. Clarity takes deliberate effort.

**Generated documentation.** Tools can turn information in the source into readable documents:

- Javadoc reads declarations and documentation comments in Java source files. Its standard doclet (the pluggable part that produces the output) creates HTML.
- arc42 documentation (see the arc42 Architecture Documentation Template article) can be built and published by a toolchain such as docToolchain, or by static-site generators.
- Generative AI can extract structured documentation from source code structures, comments, dependencies and build scripts. An arc42 building block view is one example.

**Close to the code.** arc42 recommends treating architecture documentation like source code. That means plain-text formats under version control, next to the code. See the Documentation as Code article.

**Limits.** Source code does not tell the full story. The reason a team chose a technology, for example, is often not visible in code. Human-written documentation is still needed for such rationale.

## Example

A team writes a payment module in Java. They give classes and methods clear names and add doc comments to the public interfaces. The build runs Javadoc and publishes the HTML on every change, so the interface description always matches the code. The team also keeps a short text file next to the code. It explains why they chose a particular payment provider, because the code cannot show that.

## Trade-offs

Self-documentation lowers the effort of keeping documents current. But clear code needs deliberate effort, and code can be gibberish. Generated documents show what is in the source. They do not show why decisions were made, and they do not tell the full story. Teams still need written rationale and context next to the code.



## Checks

- Interface or API documentation is generated from the source (for example with Javadoc) instead of written separately.
- Architecture documentation is stored as plain text under version control next to the code.
- Documents are built and published by a toolchain, not assembled by hand.
- Rationale for technology choices is written down by humans, because code does not show it.
- The document does not claim that code alone is the full documentation.

## Related

- [Documentation as Code](https://arc.fuet.ch/concepts/documentation/documentation-as-code.md)
- [Traceability](https://arc.fuet.ch/concepts/principles/traceability.md)
- [Design for Change](https://arc.fuet.ch/concepts/principles/design-for-change.md)
- [Architecturally Evident Coding Style](https://arc.fuet.ch/concepts/fundamentals/architecturally-evident-coding-style.md)
- [Domain-Driven Design](https://arc.fuet.ch/concepts/domain-driven-design/domain-driven-design.md)
- [Guidelines for Documentation](https://arc.fuet.ch/concepts/documentation/guidelines-for-documentation.md)
- [arc42 Architecture Documentation Template](https://arc.fuet.ch/concepts/documentation/arc42-documentation-template.md)
- [Diagrams as Code](https://arc.fuet.ch/concepts/documentation/diagrams-as-code.md)

## Sources

- [Code As Documentation](https://martinfowler.com/bliki/CodeAsDocumentation.html) — martinfowler.com, accessed 2026-11-09
- [arc42 Documentation - arc42](https://arc42.org/documentation/) — arc42.org, accessed 2026-11-09
- [Will we soon stop writing architecture documentation ourselves?](https://www.isaqb.org/blog/will-we-soon-stop-writing-architecture-documentation-ourselves/) — isaqb.org, accessed 2026-11-09
- [javadoc-openjdk27(1) — Arch manual pages](https://man.archlinux.org/man/extra/jdk-openjdk/javadoc-openjdk27.1.en) — man.archlinux.org, accessed 2026-11-09