Hands-On: Designing Documentation that Users Can Actually Use

A little knowledge is dangerous. This is sometimes the case with software users. They’re more tech-savvy than ever before. Sometimes, they try to resolve common technical issues on their own. They might get frustrated, though, if they can’t find the information they need.

Worse yet, they might apply the wrong solution — or incorrectly apply the right solution — because the documentation isn’t clear. This could get them deeper into trouble. They might get so upset that they give up or turn to a competitor’s product.

Developers today are striving to offer online software documentation that is user friendly, allowing users to search on their own for solutions to solve common problems and learn how to successfully implement those solutions.

Documentation portals: A trend worth following

The current trend in online software documentation is to create an information portal that puts all the documentation in one spot, making it easier for users to find the information they need.

Because users learn in different ways, portals often include information in different formats:

• How-to tutorials in both article and video formats are especially useful for people who aren’t tech-savvy or who need to quickly get up to speed with some aspect of the software.
• An FAQ page is also a good idea. Many people check this type of documentation first.
• Forums give people a place to ask questions that aren’t answered on the FAQ page. Forums should be monitored by your internal experts, even if you allow other users to comment on the questions.
• If you allow users to modify your software or integrate it with other systems, you might want to include a knowledge base of in-depth technical articles. Although these articles are written for IT professionals and developers, they should still be written in a clear, concise manner.

Design tips

Software users are accustomed to modern websites, so your documentation portal should sport a modern design that matches the look and feel of the Web. Here are some ways to accomplish this:

• Make your documentation portal easy to navigate. Every page should include navigation controls that are easy to see and use. Including a “Back” button is especially important so that users can get back to where they were.
• Use white space in your documentation pages, but don’t overdo it. Cramming as much as you can into a page can make it uninviting; adding white space can make it more appealing. However, presenting users with mostly blank pages will waste their valuable time, as they’ll have to click through numerous pages to get the information they need. You need to find a happy medium between the amount of text and the white space on a page.
• Make sure your documentation pages are easy to scan and read. Streamline the text by taking out superfluous information that will not help users. For example, when users are trying to solve a problem with a feature, they likely don’t need to know when that feature was first introduced. The documentation should be clear and to the point.
• Use keywords that let users easily search your document pages.
• Make your documentation pages mobile friendly. Users might be looking up documentation on mobile devices, especially if your software is a Software as a Service (SaaS) offering.

Good documentation is essential

Good documentation isn’t just a nice-to-have software feature. It’s essential for customer support and retention. You can also use it as a selling point to attract new customers and grow your business.

Have you read your documentation lately? If not, take a fresh look with these tips — and your customers’ perspectives — in mind.

[cta]PxPlus will help you design documentation that’s as good as your software. If you have questions, contact us any time by email at theplus@pvxplus.com or by phone at 1-888-975-PLUS.[/cta]