Stop Trying to Make Documentation Happen

Rohan Bassett
Oct 2, 2018 · 6 min read

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.

“pencil and ruled paper” by rawpixel on Unsplash

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. Any problem which has a developer, designer or product manager reaching for documentation is an opportunity to improve our process.

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

When I started, we had a real problem with build tools, libraries and environments. Server configurations were localised to developer’s machines and could not be committed, and WordPress installs and plugins needed to be manually updated to match production. Onboarding new developers involved a lot of manual set-up and migration, and there was no enforced consistency between each developers’ environment, let alone staging or production servers.

Fortunately, another developer had been championing Docker for some time, and there was already momentum in the team to move toward easily reproducible, virtualised environments for development. After trialling different approaches, we’ve created a simple template which can be used to reliably spin up new environments, and acts as a drop-in replacement for the MAMP stacks serving legacy codebases. Some of our more complex environments are served using Vagrant virtual machines, which allow for much greater flexibility at the expense of a larger footprint and longer setup time.

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.

Test All The Things

Good commit messages help. Clean, well-structured code can be nice. Comments can be a real boon, if you’re willing to trust that they’ve been maintained along with the code. But there’s no better way to guarantee that code works, and will continue to work, than a well-defined list of test cases to check that the code actually does what it’s supposed to do.

Automated tests are essentially documentation written in code; whether they guarantee business requirements are followed, or just make sure that Widget A can send data to Widget B, they will ideally provide a list of everything the code is responsible for achieving. With good test coverage, you can comfortably fix a bug that rears its head at half-past-four on a Friday afternoon, while ensuring that your changes aren’t adding exciting new bugs of their own.

Like many companies before us — AirBnB being a prime example — we all believe in the usefulness and the merit of good testing, but the realities of actual work and day-to-day life means testing is most often only performed once the work is done; and anybody touching the codebase weeks, months, or even years from then needs to manually perform the same checks.

We’re not yet at their level of sheer coverage, but we’re improving — especially as we work on increasingly complex solutions that provide plenty of tricky, edge-case scenarios that can take advantage of the benefits offered by automated testing. The more we consider testing as happening in tandem with development — and not as some extra, unrelated work at the end — the better we’re placed to validate our approach and our solution, and to ensure that we can always guarantee each day of work is adding to a solid, well-tested foundation.

Show And Tell

Finally, documentation is always considered as something that will be useful later on — but there’s also value in sharing knowledge and findings now, while everything is still fresh and relevant.

At 24, we have daily stand-ups to report on progress and priorities, weekly company-wide showcases, and two dev-team meetings each week to share our findings and any problems or discoveries we’ve experienced. We have a strong ethos of cross-department communication and knowledge sharing, and a transparency around the various processes each team follow.

At a business level, this is valuable for producers who need to allocate resources; individually, it helps to know that my technical decisions can be validated through sharing with the wider team, and that someone else on the dev team might have recently worked to fix a bug similar to the one I’m tearing my hair out over.

There is still a lot of work to be done on this front, though. We’re currently working on a skills matrix to determine the best point of contact for any tech work or queries (as well as identifying gaps for when we hire!) and there’s recently been a push to have developers more involved in future sales work, so we can present more tailored technical solutions to clients. This ongoing sharing of knowledge and involvement helps everyone feel more confident in the work we’re pitching, producing and presenting.

Summary

Documentation is important and will always have its place, but it’s just as important to consider each apparent case for documentation as a reason to improve elsewhere in the business. By limiting the scope of documentation, we can ensure that the necessities — the decisions, business logic, scope and requirements — are captured without being hampered by a need to document All Of The Things, which inevitably leads to a confusion of Confluences.

We’re always looking for new ways to improve our processes, and we’re always keen to hear from people who share our ambitions of growth and development. If you’ve got a tricky problem to solve, or want to be a part of the exciting new projects we have in the works, drop us a line!


Rohan Bassett is a Senior Developer at 24 Digital, a digital product design agency based in Melbourne, Australia.

About 24:

Instagram — @24_digital

Linked In- https://www.linkedin.com/company/24digital

Website — 24digital.com.au

We want to work with ambitious people & businesses to create amazing things. Does that sound like you? Say hello — hello@24digital.com.au

24 Digital

Discover the inner-monologue of the team from 24 Digital - a group of creative technologists looking to enhance the human experience through digital solutions.

Rohan Bassett

Written by

24 Digital

Discover the inner-monologue of the team from 24 Digital - a group of creative technologists looking to enhance the human experience through digital solutions.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade