Fighting Entropy — Personalis
Introduction
I remember joining my first software team and being incredibly frustrated with the lack of documentation. The team had existed for a couple of years already but documentation on how to build and develop the service was sparse. I brought this up and the response was that documentation would go out of date immediately and therefore creating it would be useless. I found this argument illogical, given that we were in the industry of building software. Our job was to create and maintain systems that are in a constant state of degradation. In essence, we were fighting entropy.
Fighting Entropy
The most visceral experience of the effect of entropy in the software engineering world is that of trying to build a package or application years after its last release. The compiler has changed; some of the dependencies are on a newer version and the old version has been pulled due to a security issue. The build fails due to a dynamic linking issue. It hurts and it is frustrating, but that is just part of the job. The package is needed, so the problem needs to be solved. You scan the logs and Google the error codes, and finally find the Stack Overflow post that solves the problem. You update the build pipeline and move on.
Yet, even though it is a similar experience when it comes to documentation, somehow it is not worth it. The reason for this is that the benefit of good documentation is not immediate, and therefore the cost/benefit analysis is skewed. In the case of software, you build it, you run it and you get the outcome you want. With documentation, you write it and then the benefit is only felt at some indeterminate later point, with faster onboarding or recovered context.
Co-Location
Often documentation is stored separately from code. Maybe there is an internal wiki or shared drive. This means that the context needs to be duplicated, once in the code and once in the documentation. Rather, create a single place for context to be stored, next to the code and then generate documentation from it. This lowers the cost and chance of the documentation going stale. The prose will still drift as the code changes, but now it is right there in front of your face and only needs to be changed in one place.
This can be implemented as a team-level process and enforced using linting. Have CI fail on undocumented interfaces or go even further and have it warn on function bodies that change without a change in comments. Though this does not cover all forms of documentation, such as architectural decisions, it is surprising how much you can store in comments. I would encourage you to push more context into this space. The benefits of co-located documentation are also more immediate. It makes reviewing the code easier, as reviewers can gain context without leaving the review. Also, AI-assisted coding benefits as the context is easier to provide to the agent.
A good example of documentation generation is cargo doc from the Rust ecosystem. Write your comments next to the code and then an HTML site is automatically generated. This is not new; Doxygen has been doing it for decades, but the tools are getting better and each modern language has its own version. For example, TypeScript has TypeDoc and Go has go doc.
Cargo doc goes even further by allowing examples to be written in comments and then tested against the code using the doctests subset of cargo test, further preventing staleness.
Do-Nothing Scripting
Another common type of documentation is runbooks, for example, a build and deploy runbook or incident debug runbook. These are important use cases for documentation, because getting something wrong or not being able to do the work has direct customer impact. There is an opportunity here to use documentation as a stepping stone to a robust, automatable system that even new team members find easy to learn and use. This further increases the benefit of good documentation.
Do-nothing scripting, from Dan Slimmon, takes these runbooks and converts them into shell scripts that at first just print the next action, but over time the script can be automated to perform the actions itself. This has a two-fold impact: it lowers the amount of manual work needed, while ensuring that the steps stay up to date. If you would like to know how to implement this for your team, you can read more on Dan's blog.
Final Thoughts
There is a lot in common between maintaining software and documentation. By using modern tooling and techniques the benefits of good documentation can be enhanced and felt immediately, just like with software. You are still just fighting entropy.
Want to stay up to date?×
© 2026 Sylvan Smit