Documentation is important, but most do it for the sake

Documentation is important, but most do it for the sake of it and, in the process, often fail to document what’s important.

Either companies 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 stale documentation.

For concepts that evolve quickly (fluid elements), I prefer to place comments next to the code, 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 productive, and for experienced folks to refresh their memories without much pain.