Tech Tuesday: Documentation – A Necessary Evil?

9 August 2016 | Nick Russell | About a 5 minute read
Tags: Agile, clients, Docker, documentation, Google Docs, Scrum, tech, Tech Tuesday, Trello

Documentation isn’t the most charming of tasks, most of us will admit that. And that’s because as people who love building and delivering great digital products, documentation is seen as an activity that prevents us from moving towards release at pace and showing clients what we’ve been working on from a functional perspective before our competitors try and achieve the same!

Digital professionals are surrounded by change, and it’s this change that drives the demand for our services. Dealing with change effectively requires knowledge and experience, the downside of this being that if the relevant knowledge and experience around the development and usage of a specific product isn’t readily available to the right people in good time, change becomes challenging very quickly.

In the short-term it can be difficult to see clearly the returned value of documentation but in the longer term payback on the time and effort invested into documentation becomes much clearer.

For example, imagine joining a mature project team working on the delivery of an existing product where no background reading on the product and development processes was available. What about working as part of a new team, having to investigate the operation of a legacy system that has zero documentation readily available to help you piece together the fundamentals?

In both these examples, and across the wider landscape, documentation increases the ease of onboarding new team members, reducing the effort required to bring team members up to speed within areas of product development they are not so familiar with. This is especially important when one-to-one time is limited, as tight deadlines naturally drive us towards focusing on tasks that create and build features, as opposed to upskilling the team.

I’m not saying that all documentation is helpful, especially when the quality is low. But some is, more often than not, better than none, which brings a rather amusing quote by Dick Brandon to mind:

Screen Shot 2016-08-09 at 10.05.54

So how do we make it easier to work on documentation alongside delivery? How do we encourage teams to produce great documentation, at least some and not none? Below provides information on the tools and process used by the client team here at AND Digital to address these questions.

Working for the client, our team has been presented with the challenge of learning how to operate a 10+ year old existing system, documenting our understanding of the platform as we go. We’ve learnt about the importance of having the right tools and processes in place to encourage documentation; learnings put into practice, which can be used at any of our clients to help make documentation easier to both complete and maintain.

On the project no existing documentation has been made available to us and we’ve had limited time with platform specialists to ask questions around the setup and usage of the client platform. A need to create documentation that was self-repairing and “almost alive” was made clear by the client as we’ve explored the system and what it offers; something that could be opened to those requiring access to knowledge, something truly collaborative that could be shared and referred to throughout the project lifetime and beyond.

The team has worked towards achieving a fluid, fast and fixable solution alongside the more functional deliverables requested by the client. Using a set of cloud-based tools and an agreed documentation process across the team we’ve set up something that is proactively used by AND Digital and the client employees day-to-day to share the developing understanding of the technology being worked on.

The set of tools we’ve used to aid a collaborative documentation approach consists of a MediaWiki, stored in a Docker container on an AWS instance, Google Docs, and a Trello board, used as below:

MediaWiki – A secure online Wiki holds a set of structured pages around project processes, and technical and product knowledge. This is aimed to be lightweight and provides links through to full documents held on a team Google Drive, while providing an short overview of the content held within each document. Access is provided to team members on a case-by-case basis.

Google Docs – A set of online documents linked to from the Wiki containing the full details behind what is presented on the Wiki. An admin member owns the Drive and provides/denies access as requested.

Trello – set up for Scrum this online tool is used to track the project team’s progress against deliverables and aids the documentation process outlined below.

Our definition of done includes the task of adding to, updating, and creating a new space on the wiki to store and share learnings discovered throughout the investigation of the client platform. This approach forces the Scrum team to estimate for documentation effort during sprint planning, which means that it is accounted for within each sprint. It’s the ownership of the team to ensure that documentation exists and is reviewed before labelling a ticket as done.

An online approach for documentation has its advantages and risks. Some of the key pros and cons associated with following an approach like the one outlined in this article are highlighted in the below table.

Screen Shot 2016-08-09 at 10.17.38

An awareness of internet security is strongly advised to minimise risk of unwanted access or leakage of sensitive data (how to address the associated risks, however, is another area entirely).

In conclusion, as professionals we understand the importance of documentation and most likely will have experienced first-hand the downfalls of not having documentation to review. There are a myriad of online tools that digital teams can use to encourage ongoing documentation alongside delivery. Understanding the risks associated with online tools is important, but when considered and appropriately mitigated the use of the cloud to foster collaboration really presents value.

The tools and process used by the client team at AND Digital have truly helped us to maintain a consistent amount and a high quality level of documentation, from the project’s inception right through to today, and these insights into our team approach can be presented as an opportunity to any of our clients.

I hope you have enjoyed reading this post and warmly welcome any questions on this article – please do leave a comment!

Enjoy documenting!

Read More From This Author

Share this blog post

Related Articles


We’re looking for bright, dynamic people to join our team!

Discover More Roles