Good documentation is like lasagna, because it has multiple layers.
Each layer serves its own purpose -
- Code layer: Great variable, function, and class names that make it clear what the code is doing
- Comment layer: Inline, function, class, and file-level comments and docstrings that explain why the code works the way it does
- Readme layer: Internal engineering-focused documentation that explains larger concepts and usage in the project & lives alongside the code
- Wiki layer: Company shared documentation that provides high level overviews, architecture decisions, & links to more detail (e.g. Confluence)
- Public layer: External documentation like API docs, public packages, and help articles
When you write a comment, think, "Could I make this comment irrelevant with a better variable name?" or "Does this comment really belong in the README?"
When you write a Confluence page, think, "Should this documentation really live alongside the code instead?" or "Would it be useful to share this context publicly?"
Each layer has its own benefits and drawbacks. Use them wisely to make your software more understandable.