When I made the move from a large media company to a much smaller agency last December, the biggest surprise was the wide variety of codebases, repository sites, hosting companies, issue trackers and build tools still in active use. Likewise, the biggest challenge was getting up to speed, quickly, without the specialist knowledge of predecessor devs or the historical context to explain design and technical decisions.
As a result, one of the targets for my three-month review was, put simply, “Documentation”. We all knew this was an area for improvement, and we had honest and thorough retros where documentation was consistently called out as a pain-point. Even if the rest of the project was a success and the client was happy with our delivery, we knew that a lack of internal documentation spoke to a dangerous culture where ongoing work would become more difficult, and new developers would take longer to deliver their best work. As a developer who came into the industry by way of an Arts degree, I felt this would be a good challenge and a satisfying job to own.
Months later, though, I’m re-assessing this need for documentation, in the way that a hardboiled detective finally recognises a red herring. A lack of documentation has never been the real problem; even a lack of current documentation has never been the real problem. Each of the problems we attributed to a lack of documentation was actually symptomatic of an improvement to be made somewhere else.