Information developers are professional users of all sorts of technical documentation, and our experiences inevitably range from genuine pleasure to absolute disappointment.
Our trained eye immediately picks out the obvious typos or inconsistencies. But how come that some texts, though technically and grammatically correct, just do not work the way they are intended to? With all the rules and guidelines, we often forget about the most important focus of technical documentation – the user. So, what is this usability factor that makes a document easy to understand and work with?
Write for usability
We do not have to be experts in usability to write in a way that helps the users find and understand the information they need. With all the style guides piled up on our desks and stored on our hard drives, we should keep in mind that following them is not a goal in itself – most importantly, it results in creating a documentation that is convenient and useful for your audience.
In my opinion, if we shift our focus to the user, we will see that many too-well-known writing strategies and best practices offer great advice for creating a usable document.
Some of these best practices are as follows:
It is common knowledge that we have to be consistent – in particular, when using terminology and naming topics and sections. Is it that crucial for the user? My answer is – yes, definitely. Our job is to facilitate understanding, not to complicate it. You should not confuse the user with different names of the same concept.
Let’s say, if the whole section is about managing database entries, and its topics are named Create an entry, Edit an entry, and so on, do not name a topic Delete a file, even if in your software application a file actually means the same as an entry.
Similarly, if you have named a topic Create a folder, do not name the next one Deleting a folder – use the same verb form. Thus, by using a consistent grammar structure you will help users scan the information and find the needed topic by its name quicker. This may especially come in handy for non-native-speakers who may find the usage of various verb forms confusing.
- Styles and formatting
By using styles and formatting you can make your document easily scannable. No doubt, we all use the specific styles for procedures, lists, notes, tables, etc., so it is a bit of an old news. But note that we do this not just for our own convenience.
This helps the user to quickly accept “the rules of the game”. For example, bold formatting is eye-catching, so this must be something important. If procedure headings are in blue, the user can scan the text for these specific chunks to quickly find the instructions and skip the intro.
- Grammar, tone, and voice
As strange as it seems, while trying to write a grammatically correct piece of text, we often forget about the user – who actually will read our message. I do not mean the simplicity of the structures – this is what we all are trying to achieve in the first place.
During the past decades, the style and tone of the technical documentation has significantly shifted from the cold third-person “the user” to the more informal and friendly “you”. Keep in mind this user-centered shift even on the level of grammatical structures and sentences.
For example, try to avoid the passive voice in cases where it is the user who performs an action.
This message appears when you start the application.
This message appears when the application is started.
If the application adopts multiple user roles, make sure to clarify who exactly you are referring to.
You can configure application settings.
As an Administrator, you can configure application settings.
However, in warning or error messages, you should use the passive voice to avoid giving the impression that the user is to blame.
The file was not found. Verify that the file name is spelled correctly.
The file was not found. Verify that you have spelled the file name correctly.
- Structure the document logically
Obviously enough, we break our writing into sections, topics, and paragraphs. As mentioned before, specific attention must be paid to consistent naming of the topics.
Additionally, topic names should be unique. The document cannot contain two topics with the same name Create a file, even if an application allows creating a file in several ways and places. Merge these instructions into one topic.
As to the structuring, follow the natural workflow. For example, do not put the topic View an entry before the topic Create an entry.
Similarly, start explanatory topics with the facts that the user is familiar with, and then proceed with the new information.
It is a scientific fact that users perceive graphics much more easy and quick than text. Presenting complex abstract notions and general workflow of an application in graphical form might be time-consuming for you, but it definitely spares the time of the user.
As to the screenshots, use them wisely. They are not needed for a simple procedure with an obvious interface where the needed controls are easy to locate. For example, placing a screenshot of a dialog box with the OK and Cancel buttons would be a mere waste of the document space.
Following the principles of minimalistic writing is the strategy that never fails. Do not overload topics with everything you can mention on the subject. For example, a small topic on an API command does not require a lengthy introduction on what the application API is and how to work with it. Such topic would require only the description of the command syntax, description of its parameters, and some examples. Instead, put the general information into one introductory topic at the beginning of the API section.
The guidelines above basically focus on the users whose task is to find and grasp the needed information and follow the instructions as quickly as possible with the minimum effort.
From writer to usability tester
As a writer, you get immersed in your text. As a consequence, you almost certainly lose the fresh and critical view on your document. You can guarantee that you have followed all the best practices for writing, but does your documentation really work as intended?
To make sure that your document is usable, have someone – your peer – test your documentation, much like the application is tested.
Trying to use your document the way your audience will is a basic and efficient test. Follow the readers’ tasks. In general, these tasks can be divided into the following types of activity:
- Following a procedure step by step (performance test)
- Finding the information (location test)
- Understanding and remembering the information (understandability test)
More specifically, perform all the casual tasks the users would do, for example:
- Find the needed information
This can be a tedious task if your document spans multiple topics. A rule of thumb is to identify the key use cases and test if your document covers them scrupulously enough.
Evaluate the table of contents and the logical structure of the document – secondary actions like filtering and printing should not get in the way of the topics that cover the main use cases.
For example, presenting all the small topics of the What’s new section as separate entries in TOC is not a good idea. It might result in a huge number of entries right at the beginning of your TOC. Now, look at the document with the user’s eyes: right off the bat, you are overwhelmed with loads of secondary entries and have no other option than to scroll (on and on) to see the document structure and actually locate the needed section and topic. In other words, respect the time of the users, and do not make them waste it in cases where this can be avoided.
- Literally follow the instructions step by step
You should specifically check if the explanations are clear and informative even for a user who is completely new both to the application and to your document.
For example, even a purely procedural topic (like Deleting the database entries) should:
- Contain a short intro to place the user in the context of the task (for example, mention the cases when you need to delete specific entries, any restrictions for this action, and what types of system permissions users must have to perform this operation).
- Reference a broader concept topic (for example, topic about creating and managing a database or about how the data is processed and stored).
- Evaluate the layout of the document
Make sure the document contains no “visual blunders”. For example, check for any lonely list entries that skip to the next page.
Screenshots and notes should be placed at the same page with the main instruction.
Another best practice is to put a non-breaking space between articles and nouns, so that an article is not left alone at the end of a line.
- Test the screenshots: graphical integrity test
You should remember that graphical information helps the users process information much faster than the text alone. Make sure the screenshots are placed in the right context – after the appropriate steps of the instructions. Check if they contain all the needed information and add value to the procedure description. They should help the user to quickly locate the needed commands and menus.
If the interface of the application is complex, check if the needed controls or menus are highlighted with a rectangular shape or any other kind of selection that is used on the project.
In addition to that, make sure that all the needed information is present on the screenshot and is clearly visible. There should be no empty fields or boxes if in real-life conditions, they are filled with some data.
Similarly, dummy names like “Test1”, “Test2”, or “testnotworking” on the interface are inappropriate for the documentation. Such names as mentioned above are something we deal with quite often, and that is one of the pitfalls of working in the same environment as your Quality Assurance Team. If possible, request a separate environment where you can set up “clean” data for screenshooting purposes.
- Check all the links and references
Most often, we click through the links to ensure that they are not broken, overlooking another hidden reef – renamed topics. While most documentation authoring tools update link text when you edit a topic name, be none the wiser and double-check.
Additionally, bookmarks are a useful tool when you need to refer to a specific word of phrase in the text and not the topic heading. You can simply create a bookmark for an important keyword or a procedure and refer to it when creating a hyperlink.
Both when writing and testing a document, all your efforts should be aimed at answering one question: “Is my communication sufficient for the users to perform their tasks successfully and quickly?” Answer to this question is basically the measure of efficiency and usefulness of technical documentation.
The principles and standards of information development have become a value in themselves, and we often follow them fanatically for their own sake, forgetting who really is on the receiving side of our documents.
So let’s double-back, refocus on the users, and make their experience with the documentation painless. It is up to us to change the status of technical documentation from a piece of irrelevant text to a convenient, helpful, and informative reference. To achieve this, you have to do more than add a few commas, but the effort is worth it. Make your writing used and usable.