Writing compelling and comprehensive documentation for your user community can be both a challenge and a chore. Follow these tips to help users get the most out of your documentation.
Let's face it, we live in an instant gratification society which makes it stressful when you work in a service-oriented industry such as IT. Juggling the needs of multiple people at once, all of whom are vying for some sort of knowledge or skill you possess, can be a difficult challenge to surmount.
Therefore, it's within your best interest to offload as much knowledge as you can so your users can access and benefit from it without your assistance. Proper documentation you can consistently refer to - and count on - can be one of the greatest assets in your toolbox to keep the ship afloat and maintain your sanity.
Good documentation is comprehensive, relevant and covers the entire picture, both detailed steps/tasks as well as the overall reasoning behind the process. Here are 10 ways you can help your users get the most out of your documentation.
1. Use a centralized repository
The worst kind of documentation involves a set of emails, a Word document being passed around, or some other version of information which is held or referenced by one person at a time.
You have to keep your user guides in a centralized location; a wiki, a Sharepoint site, a Google Document or some other place where multiple people can access it at once and changes you make will be reflected instantly. The link should be widely shared and included in new employee training guides.
You don't have to allow users write permissions to the material (in fact I recommend not doing so), but everyone who needs the information - or may need it down the line - should at least have read permissions to the content.
2. Understand your audience
Determine what types of users will access your documentation as well as their background and technical skills. Writing guides for programmers or fellow system administrators, for instance, is likely to be far more technically complex than for typical end users.
On the flip side, you can take some shortcuts with the first audience - you won't have to explain how to find a machine's IP address or host name to a 20-something techie, for instance, whereas you might have to spell it out for a 60-something clothing designer. Plan your content and level of detail accordingly.
SEE: Hiring kit: Technical writer (Tech Pro Research)
3. Make the material clear and helpful
The documentation you write on a certain topic should cover all the bases, but make sure it stays on target and doesn't wander into irrelevant territory.
Provide links to other pages/sites you reference (such as changing a password or requesting a VPN keyfob) rather than copying and pasting the content into this document, since then it will have to be updated twice if the process changes.
In addition to telling users how to do something, focus on the Five Ws:
- Who is responsible for which responsibilities; if you state an account on a specific system has to be provisioned as part of your instructions, identify the responsible parties and how to contact them.
- What application, system, network or other object the documentation refers to.
- Where the instructions you're providing need to be carried out (a particular server, the local network versus VPN network, etc.)
- When to follow certain steps or contact various personnel.
- Why this process/procedure is the way it is. Establishing the "why" is left out of documentation all too frequently and can lead to resentment or frustration if users feel they're being made to jump through hoops.
SEE: 44 simple ways to sharpen your writing skills (free PDF) (TechRepublic)
4. Use proper formatting and structure
Nothing is more frustrating to read than run-on sentences, or several sentences strung together without paragraph breaks. I recommend paragraph breaks after no more than 2-3 sentences where possible.
Breaking up your content into manageable chunks makes it much more digestible, and documentation should also be written in a professional manner - rather than stating a certain server is a "slow stupid piece of junk so don't be surprised if it takes an eternity to log on" I'd go with "the system is a bit outdated so please be patient as it may take some time to connect" (and put together a plan to upgrade the system in question!)
5. Use screenshots
Screenshots provide a visual aid to help orient users to find exactly what they're looking for or gain a better understanding of the process/environment you're covering. Unfortunately, the urge to avoid adding them into documentation is frequent, since it involves additional overhead to grab screen captures, upload image files and so forth.
However, as the saying goes, "a picture is worth a thousand words" and quality documentation depends on screenshots. You can edit images to include pointers, circles or other elements to emphasize what you're stating in the guide.
SEE: How to succeed as a new IT manager (free PDF) (TechRepublic)
6. Use instructional videos
It get it. Some people hate to read. I'm not one of them, but instructional videos can help those who don't have the time or patience to wade through a lengthy document. It can also provide added clarity by demonstrating steps or tasks for users in a way they can repeat over and over as needed.
7. Formulate tough love strategies
This may sound controversial but I recommend being firm and requiring users to read documentation before asking for help on the process.
One time, I had a user ask for assistance with a procedure which was thoroughly documented. I provided them with the link to the page, but they responded with "Can't you just explain to me how to do it?"
"I have explained how to do it on this page," I replied.
"I don't have time to read it," the user replied, which frankly insinuated my time was less valuable than theirs.
"That's exactly why I need you to read it," I responded. "I have to make sure the documentation can be easily followed by individuals who are in a hurry, to make sure it's sufficiently detailed for them to navigate. This will help me to help the user community."
The user wasn't entirely happy about the requirement, but did later confirm the five or six steps listed in the documentation made perfect sense and were easy to adhere to.
8. Publicize your work
Bragging may be considered socially unacceptable, but in the case of user documentation you will want to publicize it as much as possible. Sending out emails with links to new or updated documents is one potential method, but I can speak from experience when I say not everyone reads everything - especially in an email-intensive environment.
Most information repositories can be customized to provide links immediately available upon logon, such as to "IT Documentation" or "Help Desk Guides." Many also display a scrolling feed of recently updated documents so you can easily direct users to the guide you just updated. It's even possible to use mechanisms like Group Policy to deploy desktop shortcuts such as to your documentation website for quick and easy access. Figure out how best to get your content out there so it's readily available.
9. Get feedback
Feedback is one of the most important factors in writing and maintaining solid documentation. Users and fellow administrators can point out weak or vague areas, or steps which have become obsolete or don't work properly.
Many documentation repositories permit the use of comments which can allow users to immediately point out areas which need improvement - or even compliment the clarity and helpfulness of your work!
10. Revisit and update
Documentation often becomes stale almost from the moment you click the "Save" button. In short, it's never finished, per se, but requires care and feeding. As applications evolve, your screenshots will become outdated. As upgrades occur, the steps involved with certain processes will drift. As systems are retired, host names you reference will become obsolete.
Make sure to revisit your documentation and keep it fresh. If the procedures involved are retired, delete (or archive) the pages involved to keep your documentation repository relevant and clutter-free.
- Open source documentation is bad, but proprietary software is worse (TechRepublic)
- 10 resolutions IT professionals should keep all year (TechRepublic)
- How to translate documents into different languages with Google Docs (TechRepublic)
- Five apps to take the pain out of documentation (TechRepublic)
- Developer documentation: How to get it right (ZDNet)
- APIs are everywhere, but documentation is wanting (ZDNet)
- GitHub: Open source is dominated by men who just can't communicate (ZDNet)