Last year I handed over an engineering project to a new team, the code base was in good shape, there were tests, documentation, all the good stuff. While talking the new team through the code base, I realised that most of what I talked about was all the technical decisions we had made, the pivots we had to do, the issues we ran into, and how we fixed those. This story was not documented anywhere, while it provides some of the best learnings for the new team.
This got me thinking about what makes valuable project documentation.
I think that most often the the final product is documented. And this makes sense from the perspective of the end user of that product.
But there’s another important audience, and that is the people who make this product. To inform their decision making, they need to understand the past decisions and changes in the product.
If you’re the one who is trying to understand the why of something, it’s time to get the excavator and dig up some old JIRA tickets, the occassional proposal on Confluence, and some comments given in a Pull Request. If you’re lucky you can piece things together. Unless you’re into archeology, this is probably not how you’d like to spend your time.
Imagine an engineer coming into a project, identifying a bit of code that looks smelly, doing a refactor (as engineers do), which eventually makes it into production, only then to find out that there is a reason things were done in a certain way.
And this is a small example, but imagine whole departments pursuing a feature that was built before by another team, but was killed and never made it to production. If that decision was never documented (and Bob doesn’t work there anymore), the new team will just give it their best shot, build the thing again and probably end up with the same result.
What if all of the decision making, all of The Why that went into a project was documented?
Each entry would just need:
And this document should live close to where the rest of the product artefacts live. Nothing too fancy, it could be just another Markdown file.
Maybe, most often a CHANGELOG.md is being used as a place to document What changed, the Why is often left out. I’d be happy to see The Why become part of every CHANGELOG.md out there, but it’s easier to start a new way of doing things with a new artefact.
Start documenting the most important aspect of your project, its history! It’s easy, it’s quick, and it pays off*.