Cloud technologies are awesome; it’s the reason Beaty Consultancy exists. We get to work with world-class developers and forward thinking businesses every day, and it’s so much fun. All too often, developers and technicians get caught up in the excitement of building innovative new platforms using cloud technologies, and ignore the bits they don’t enjoy. Documentation is not sexy, but it is necessary.
Why?
It’s so easy to brush off the need for documentation as something that only big businesses need. If you’re hiring consultants to produce specific units of work for your business, do you really want to pay them an extra 10-30% to document everything they do? Where does that budget come from? After all, you just want to get features out there as soon as you can!
If those sound like your sentiments, you’re not alone. Businesses need features out the door and in the hands of their user base, and therefore making money, as soon as possible. But what about when the current developer leaves the project and you need functionality extended? Finding another developer won’t be a problem, but getting them up to speed on the codebase probably will be.
What about when your startup really takes off, and you need a whole team of developers and technicians to expand and scale the platform? You’re going to wish you had documentation for them to consume and therefore be able to start work more quickly.
Who?
Everyone should be documenting their piece of the platform. Developers should add comments into the code they write. Cloud Architects should do the same to their infrastructure build scripts. Network technicians should deliver a network schema document too.
All this documentation has to be useful to the business though. It entirely depends on what that business looks like, as to what form the documentation should take. A public company might need to conform to strict documentation guidelines, and be stored in an Information Security Management System (ISMS). Whereas a startup might just need something that makes sense to the business owner, or their technology team. So within the who, we should think about ho creates the documentation, as well as who consumes it.
Or is the documentation intended for the end user? If you’re creating a brand new platform to be used by the general public, you would be amazed at the types of questions you might receive from them. You definitely need a Frequently Asked Question (FAQ) section, trust me.
What?
Everything! Well, nearly everything.
Nothing can be left to assumption, because people with different viewpoints will assume different things about the same scenario. So in code, there should be a comment about every major section or method in there. We don’t need to know what every single line does, but what does this section seek to achieve? Similarly in infrastructure and deployment scripts, what does each section add to the overall environment. That way, we can understand the impact if something in a given section were to go wrong.
When?
One of the most frustrating things is old documentation. It is literally worse than no documentation at all, because it can lead you down blind alleys. I don’t care where you used to store the logs of a given component, I just care about where it is now. So when that part of the business process changed, so should the documentation.
If I may climb down from my high-horse just for a minute, I know this isn’t always possible. So, why not review the need to create or update documentation at the end of a project, or sprint? Do it while things are fresh in your mind, and when you still remember why you made the technical and design decisions that you did.
Where?
So where should you keep all this useful documentation? Again, this all depends on the business. Most of our clients share a folder within their corporate Google Drive, OneDrive or something like Foldr if they want to tightly control their own data. But some clients use complex and vastly scalable systems like Atlasian Confluence. They all have their pro’s and con’s, but the key is to make everything relevant to the business you’re supporting by creating the documentation.
Documentation is no use if nobody knows how to find it, or if people do not have access to it. So think about your other business processes, and where you store other critical business data. Make documentation part of those processes.
How?
How do you get from a blank document to a document which smooths out deployment and support, and which ultimately saves time and money across the business? Easy, peer review!
Peer reviews are so important in the process of documenting a system. You know exactly why you created something the way you did. It makes perfect sense to you, so you didn’t bother documenting where to find those prerequisites for the new module you just expertly finished coding. But unless you have someone review your documentation, how do you know if it is any use to someone else?
My last top-tip is to include examples in your documentation. We have all been in a situation where we just can’t quite grasp the idea someone is trying to get across to us. But as soon as they give a good example of the subject they’re talking about, everything clicks. We can’t assume the reader of our documentation has the same experience as we, the writer, have.
Necessary
An of course the power of your technical documentation comes in when you integrate it tightly with the rest of your business processes. If you read our blog post on Change Management a few weeks ago, you’ll already start to see how we can use one tool to make another tool much more effective. Imagine being able to know, ahead of a given change, the impact of the change you’re going to make, or the new feature you’re about to release? It’s only when we document our processes that we can really deliver this top-tier service which users are becoming accustomed to. If our businesses don’t have the support frameworks in place to keep excellent uptime and data security, we will not flourish.
