Stop trying to make documentation happen.

2 NOV. 18 | Rohan Bassett | TECHNOLOGY

Back ArrowCreated with Sketch.

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.

As a digital agency who pride ourselves on delivering user-friendly UIs and intuitive UX, we need to remember that our process is itself a product.

Ideally, when given a task to do on a new codebase, my first job shouldn’t be to spend time on Confluence swotting up decisions made months or years ago — but to pull down the repo and go straight to, uh, the source.
To enable this best possible life, we’ve made improvements in three key areas, none of which involve the thankless task of writing and maintaining old-school documentation.


Development Consistency

As a digital agency with a roster of clients and a busy schedule of current and incoming work, we face unique challenges in promoting consistency across projects, many of which are necessarily built for different environments. There is still much work to be done on this front, but the friction involved in setting up developer machines has been greatly reduced, and we’re continuing to work towards an ideal scenario where all projects can be spun up with no specialist knowledge or edge-case configurations.

Follow us

Are you interested in working with us?

Whether you have a clearly defined brief or you're not sure wherein the problem lies; drop us an email, or give us a ring for a chat about where you are at and how we might be able to help you.

03 9005 0055