Crypts and Commits: This Documentation Isn't for You

The habit of creating documentation began for the author in 2012 while working at an EHR startup that rapidly grew from four developers to forty. The rapid scale posed challenges beyond headcount, as the product expanded with new applications, repositories, and experiments. To address this, the author started writing systematic documentation, beginning with README.md files and ONBOARDING.md guides.

As projects grew larger, the documentation expanded to include architecture notes, runbooks, release notes, and other artifacts. When new team members joined, they were often tasked with updating the documentation, which served as a quality control measure for the handoff process. The author's current workplace has a term for this process: "John-ifying a repo."

The author's documentation habits evolved organically from their personal instincts, rather than being a deliberate conscious decision. The startup experience reinforced the importance of making documentation a repeatable practice. While reading documentation is essential, it should not be blindly trusted, as it may contain stale, incomplete, or incorrect information.

The key is to strike a balance, where both reading and questioning the documentation are valued. Documentation is not a substitute for human judgment; rather, it should provide a better starting point for decision-making. With the advent of AI coding assistants, the value of this documentation habit has been amplified, but the fundamental purpose remains unchanged.

Writing documentation is like speaking to a forgetful future self; if the author returns to an old project after a long time, they need to read the context to understand the reasoning behind architectural decisions. AI coding assistants serve a similar purpose by providing context, but they do not retain project understanding between interactions.

The author believes that AI assistants can consume more documentation than a human developer would typically review, but this does not mean the documentation is free or without limits. The key is to use AI assistants responsibly, ensuring that the documentation remains a valuable resource rather than a burden.