Documentation is often an afterthought when you’re working in the tech industry. Whether it be cloud security, application development, or even system administration, no one wants to make documentation a priority. But what happens if key personnel leave, get sick, or even pass away? You’ll be left with what could be a big can of worms that might take months - or at worst, years - to unravel. This likely scenario is not only scary to imagine, but poses serious threats or issues for your organization or company in the future.
Let’s first start by defining why documentation is important. There are three key reasons: auditing, continuity, and transformation, or ACT for short.
Auditing is just what it sounds like: If a stakeholder wants to see how a process is done or you want to take a look at how something could be done more efficiently, you’ll need documentation. It’s the ultimate insurance policy. Should a system fail, you need to comply with a certain standard, or your organization is acquired or goes through a major change, you’ll need it. With documentation, you can easily and readily show how to do things without having to track someone down or redocument an established system or process.
Continuity is more important than ever in today’s world. People constantly change companies and positions. When someone gets a promotion or takes another job, how will you know exactly what they did without having them spend their final two weeks backtracking in order to prepare their replacement? More importantly, how can you help make sure the critical path of the process that was created by a consultancy or temporary team is sustainable and able to be supported? Documentation allows for continuity in your operations and processes to ensure you don’t miss a beat.
Transformation rounds out the list. One of the biggest blockers to migrating a system or process is not knowing how it works in the first place. Imagine if you picked up furniture from Ikea and there were no instructions (or even pictures) to guide you through the process of making those parts into furniture. You would probably not know where to start. This often happens when you try to migrate or transform a system towards something better. The transformation requires that you spend a lot of time upfront understanding where everything is and how it all works together so that you can easily make the changes you want to make.
So, now that you know why documentation is useful, how can you make sure it’s done well? There are four key things to remember when creating useful documentation: create organized buckets for your information, write everything down, understand your audience, and be consistent.
The French have a concept in cooking called mise en place, which translates to “everything in place.” It refers to setting everything up so that you can be more efficient with your time and movement in the kitchen. If you were going to document putting together a dresser, you might have a section or bucket on parts included, tools needed, instructions, and safety precautions to take while assembling the dresser. Creating buckets for your documentation allows you to easily dump information into the appropriate area. An example of a bucket in tech documentation is the resources required to run a system. This would include configuration information or permissions needed for each component to run the system. When you’re ready to finalize everything, you can spend your time cleaning things up instead of rewriting everything from scratch.
The next concept is super logical, but also difficult to do: write it all down. No matter how big or small, put your thoughts, changes, and everything else into those buckets you created. This is difficult because it requires you to actively remember to do something else while you may be busy making a change or fixing something. A helpful tip for writing things down is to keep a notepad, real or virtual, next to you while you work so that you can record what you’re doing. Alternatively, you could just record everything you’re doing like YouTubers do and go back and outline the steps you took to make something happen.
Understanding your audience is key for a few reasons. Firstly, you don’t want to write or produce something in a fashion that is difficult for them to understand. Next, you don’t want to make it difficult for them to access. Here are a few questions you can ask yourself when you’re creating documentation:
What is the goal of this documentation?
Who is the intended audience?
Where and how do they typically consume documentation?
What am I trying to communicate with this documentation?
How can I make this easier or clearer?
The last and most important point is to be consistent.
If you’ve ever watched tradesmen work, you’d notice they have a routine. They come in, set up, work systematically, and clean up at the end of the day. Your process should be similar; you can simply record or add to the documentation you have started every day. This way you can build a habit, which allows you to always make sure that you’re documenting everything and create an example for others in your company or organization to follow. You have to be the change you want to see.
The last item is how to help make sure others in your organization buy into documentation. One of the best ways is to create a process with templates. A popular example is a Slack bot that is set up every week to remind the team to fill out a template with the work they’ve completed. This lets you jump in to help organize their thoughts and also allows for audit capability. Templates make it easy and accessible for others to quickly and consistently add information in an organized fashion, allowing you to transform it as you see fit.
Documentation can be a difficult thing to keep track of and tedious to keep up with, but you can be consistent and successful by using the following tips:
Documentation is important for auditing, consistency, and transformation (ACT).
Get better at documentation by:
Creating organized buckets for your information
Writing everything down
Understanding your audience
Being consistent
You can get more buy in to documentation at your organization by creating templates and helping facilitate the process.
Don’t let documentation slow you down, instead own it and allow your organization to stay nimble as new opportunities and challenges arise.