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.
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.
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.
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.
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.
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.
Necessary cookies are absolutely essential for the website to function properly. These cookies ensure basic functionalities and security features of the website, anonymously.
Cookie | Duration | Description |
---|---|---|
cookielawinfo-checbox-analytics | 11 months | This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics". |
cookielawinfo-checbox-functional | 11 months | The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional". |
cookielawinfo-checbox-others | 11 months | This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other. |
cookielawinfo-checkbox-necessary | 11 months | This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary". |
cookielawinfo-checkbox-performance | 11 months | This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance". |
viewed_cookie_policy | 11 months | The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data. |
Functional cookies help to perform certain functionalities like sharing the content of the website on social media platforms, collect feedbacks, and other third-party features.
Performance cookies are used to understand and analyze the key performance indexes of the website which helps in delivering a better user experience for the visitors.
Analytical cookies are used to understand how visitors interact with the website. These cookies help provide information on metrics the number of visitors, bounce rate, traffic source, etc.
Advertisement cookies are used to provide visitors with relevant ads and marketing campaigns. These cookies track visitors across websites and collect information to provide customized ads.
Other uncategorized cookies are those that are being analyzed and have not been classified into a category as yet.