Documentation is important, but most companies do it wrong ⚡

Documentation is important, but most companies do it wrong ⚡

Either they make you document everything, or there is no documentation at all. In companies where some documentation exists, it is mostly stale and outdated. So, what should we document and how to get it right? Here’s my thumb rule

1. document static elements in a documentation tool
2. document fluid elements in the source

If the system or requirements are ever-evolving then documenting every minute detail yields diminishing returns. Either it requires us to put in humongous, consistent effort to keep it up to date; or someone might build an incorrect understanding of the system by referring to a stale documentation.

For concepts that evolve fast (fluid elements), I prefer to put the comment next to the code; while keeping them concise and crisp to make it easier for engineers to understand the code. PR reviews can ensure code comments are in sync with business logic changes.

I prefer to have verbose documentation in some documentation tools for static elements like

1. a very high-level overview,
2. terminologies used in the product or codebase, or
3. the core algorithm powering the product use case.

This way, we still have enough documentation to get anybody started and make them productive, and for experienced folks to refresh their memory without much pain.

⚡ I keep writing and sharing my practical experience and learnings every day, so if you resonate then follow along. I keep it no fluff.

youtube.com/c/ArpitBhayani