Creating Usable, Meaningful Documentation in 5 Easy Steps

I remember starting my first IT job in 1999, as a Desktop Specialist. I was hungry to learn and excited to find my place in this new organization and role. I talked with my Desktop Manager in regards to documentation, and she stated the document should, above all else, be clear. Clear enough that we could pull someone with minimal IT experience off the street, and they would be able to use the document to complete whatever process was defined in the document.

I really took her advice to heart, and I have tried to apply it every time I am assigned the responsibility of providing documentation. The first time I realized I was getting good at documentation writing was two years into my role as a Desktop Specialist. I was on vacation. Since I had provided solid documentation for my processes, no one was calling me. I was truly on vacation!

Here are my steps for creating usable and meaningful documentation.

Step 1: Know the Product

In order to know the product, you must take the time needed to learn the product (live and breathe it on a daily basis). What comes with every product? A manual, or sometimes multiple manuals. Take the time to read each chapter. Make sure to keep referencing these manuals until you get a good feel for the product.

Remember, any time you don’t know something, you should reference the manual. It’s not cheating! If there’s a section you don’t understand, be sure to leverage the makers of the product. Contact their product support team. They should already have specific documentation for every process or function their product can do. They will also be able to point you in the right direction for your specific question.

Step 2: Include Screenshots

Let’s say, for example, I’m documenting the “Initial Login Process for a Remote Access tool.” I want to know each step the user would go through to complete this task. What I have found to be helpful are pictures. Pictures truly are worth a thousand words. When a user clicks a button or saves a configuration page, what should they see next? You can try to explain the details on the returned screen, or you can simply capture a screenshot. The user can use the screenshot as a reference point to know exactly where they’re supposed to be.

Step 3: Organize The Steps Sequentially

Make sure you organize each step in a sequential order to create a process flow. If the steps are out of sequence, your end user will be lost. This is a time-consuming process, but believe me, it’s worth the effort. Once you have these steps down, you have the template for the application.

Future releases may contain minor changes to the screens, or rebranding of the application (e.g. if another company bought it). Since you still have your template, all you need to do is take a new screen shot to replace the old, or rephrase your sentences. Again, your initial hard work will save time and effort when future changes are needed.

Step 4: Know Your Audience

So far, you’ve taken the time needed to understand the product. You’ve also taken the time and and effort to step through the process and organize it as needed. Now you have to know your audience. Who’s going to be using the documentation you’ve provided?

If it’s the Service Desk, you need to write the document in a way they can understand. If it’s for experience System Administrators who’ll be using the documentation as a runbook, you shouldn’t have to break each step down. These folks should already know how to perform a specific function they’re used to. You don’t want to insult their intelligence by telling them how to do a process they do every day. Either way, you should make sure every part of the process is defined, so they know what they need to do when they follow your steps.

Step 5: Review and Test

Now is the moment of truth. Gather your core team members, and have them review the process flow you’ve mapped. Sometimes after spending days on a document, you may not see minor things—since you’re familiar with the application. Provide the documentation, and walk away. If there are no questions, it was a success. If there are questions, review, and fix your steps as needed.

Following these steps will let you create documentation that is useful to existing staff and future employees. It will be clear and concise and easy to modify going forward if software or processes change due to new features or added requirements. This also means you will be enabling your organization to get the most out of the software or processes you’re describing in your documents, which makes everyone’s work life easier. But if you still have questions about the best way to create useful, meaningful documentation, please don’t hesitate to reach out to us. We’d love to help you get started.