This post originally appeared in Human Infrastructure Magazine, a bi-weekly newsletter available free with a Packet Pushers membership. Get details and sign up here.
Documentation is an ingrained part of my work life. From force of habit, I create a process whenever I’m doing something that took a bit of time to sort out.
What’s In My IT Process Documents?
- Context. When writing a process document, remember that your audience hasn’t been where you have, which is why they are reading your doc. For technical people, understanding why they are doing something often answers many other questions that might come up. It’s worth writing a few sentences to explain the context.
- Reasoning. As the document progresses, I’ll often explain my logic for executing a step in one way or another. I might mention the risks of choosing a specific option. This educates the reader so that they are not only following steps, but are also learning along the way.
- Process. Many of the documents I write are procedures, where several steps are required to complete the task. I make clear distinctions between each part of the process. Simple enumeration (1, 2, 3, etc.) works best for me.
- For more info. In the theme of educating the reader, I document where I found all of the information to being with. Let’s say the process is about standing up a routing adjacency with a particular set of options. I’ll include links to the vendor docs that explain the scenario. If you found a kernel of wisdom on a forum or blog, consider copying & pasting the important text to go with the link. Forums and blogs have a way of disappearing from the Internet.
- Simple language. Documentation is not the place to write in an elevated style. Don’t attempt to impress the reader with your brainpower. You’re enabling the reader to perform a task confidently, so use clear, simple language. If you’re a new author, give your process to a co-worker see what questions they have. Update your doc to answer or eliminate those questions.
- Collaboration. When writing a document for your organization, that doc is for the benefit of everyone. Your mindset should be that the doc belongs to the company, not you. In that context, documentation is collaborative. Others on your team should feel free to refresh documentation as needed.
- A helpful title. Write a title that’s as concise as it can be while still explaining what the document contains. “Email Doc” is a terrible title. “How To Flush Stuck Outbound Messages From The Internet Mail Queue” is more descriptive without being too long.
- Marketing. While you’re not trying to sell your document, you do need to market it so that your co-workers know of the available resource. Shine a light on your document. Feature it on the front page of the wiki site. Send an e-mail to the group. Mention it in a team meeting. No one will benefit from your document if they don’t know it’s there.
Now Go On Vacation
The upshot of good documentation is that it’s a stand-in for you. When you are out of the office for travel or personal time, you want to be bothered as little as possible. If you can refer your co-workers to a document, they can “bother” the document.
If you’re fortunate, your co-workers will update the document themselves over time, disconnecting the process from you individually. You don’t want to be forever involved in a process just because you’re the first one to figure it out. When documentation is part of your IT team’s psyche, everyone creates, refers to, and maintains documentation, taking joint ownership of processes.
If you’re in management and don’t see documentation happening on your team, foster it through example. Start writing documentation, and encourage your team to do the same. Living documentation should become the operations handbook of your organization. It should survive staff turnover and be a ready resource as team members come and go.
