Code Explains What, Docs Explain Why

Thoughts on documentation and its overlooked role in development

Tags: devprocess, documentation

---

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.

1. Code Comments

• 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.

---

---

Tags: devprocess, documentation
Updated on: 2025-07-12