We all agree on this, documentation is boring. It’s the first thing that
gets dropped when deadlines breathe down your neck. But maybe it’s time
we stop treating docs as a “nice to have” and start seeing it as a mirror
for better software.
You don’t need to document everything
Seriously. Good code is self-explanatory.
If your function is named ‘fetchUserProfile’, and it takes a ‘userId’, I don’t
need a comment saying “This function fetches the user profile”.
What we need to document are the things that aren’t in the code:
- Why we chose it as a micro-service over module
- Why this service doesn’t retry
- Why we assume the number of users will never cross 10k
- Why this function breaks
SRP on purpose
- Why this file exists even though it looks unused
These are not visible in your code, and no amount of clever naming will fix that.
Documentation is self-analysis
It’s not just about sharing knowledge with others. Writing docs forces you to
think. When you explain the why, you often discover things you never noticed.
- You write: “We assume this will scale linearly…“
- Then pause: Wait, will it? What happens at 1Lac records?
That tiny moment of doubt leads to better questions. That’s gold. Documentation
is where your design meets your doubt.
Where to Document Things
Not everything belongs in the same place. Here a practical guide to what to
document and where to put it — starting from code and moving outward.
- Add only when something is non-obvious.
- Explain hacks, edge cases, constraints, and assumptions.
- Avoid repeating what the code already says (‘i++ // increment i’ is not
helpful).
2. Git Commit Descriptions
- Write meaningful commit messages with context.
- Focus on why the change was made, not just what.
- Link to related issues or decisions if applicable.
3. ‘README.md’ (in each module/folder)
- What this module does.
- Setup/config instructions.
- Any known limitations or context-specific notes.
- Acts as an onboarding doc for anyone new to the code.
4. ‘docs/’ Directory (inside repo)
- Design documents, diagrams, assumptions, FAQs.
- Explains why the system is built this way.
- Cross-cutting details not obvious from reading individual modules.
5. Wiki / External Docs (outside repo)
- High-level documentation: business logic, product context, or team processes.
- Useful for non-developers (PMs, QA, support).
- Should link back to relevant code/docs if needed.
6. Code Annotations / Docstrings
- Use language-specific tools (JSDoc, TSDoc, etc.) to document interfaces,
function params, return types.
- Helps with IDE tooling and understanding public APIs.
Every level of documentation has its purpose. Use the right one for the right
kind of information.
Validate Your Documentation
One simple way to check if your documentation is useful:
- make your junior or mentee read it and try to build or explain the system
using only the docs. If they ask good questions, that’s a sign your docs
helped them think. If they’re confused, that’s a sign something’s missing.
- present your design or README to the team; turn it into a short
walkthrough, followed by a healthy discussion or debate. You will quickly
discover blind spots, assumptions, or unclear decisions.
BTW, Good documentation isn’t just a record; it’s a conversation starter.
What’s next?
Use docs to talk to your future self and future teammates. Tell them the
context. Tell them what might change. Tell them what to watch out for.
Trust me, 6 months later, you’ll be glad someone did.
So yeah, code tells you what the machine should do.
Docs tell you why a human decided that’s the way to do it.
We need both.