The quality and effectiveness of all documentation can be measured against three traits: readability, accuracy, and discoverability.
These traits are often used to determine documentation quality, but you can also use them to establish goals for creating a documentation strategy.
While the prose is an essential factor in documentation, readability broadly considers who the documentation is targeted toward and how it's written.
To be truly useful, your docs must address the needs of specific users. When you craft your documentation plan, it's essential to ask yourself these critical questions about your readers:
Determine the identity of your users and what they need to succeed. If your user base is mixed (users with varying levels of expertise or knowledge), organize your information architecture in an organized format that divides technical content by complexity or a hierarchical structure that takes users from basic to more complex. Regardless of your audience makeup, determine the key issues to convey and how your docs address their specific needs.
Understanding who's likely to consume your documentation significantly influences how it's created. Establishing one or more reader personas will define how technical and detailed the documentation should be.
User personas established for marketing campaigns and usability plans may not necessarily be the same personas used for documentation purposes, as the buyer isn't always the same person as the user.
Always write for your most challenging reader, not your most agreeable one. Most readers don't want to sift through a ton of text to get an answer. Others have a hard time understanding business jargon. Some readers always take ambiguous wording the wrong way.
Using everyday language and avoiding ambiguity can drastically improve any document's readability.
Documentation is typically split between two types of information: descriptive and task-based.
Both types of information are necessary within documentation. Splitting them into two distinct sections is recommended to improve readability.
Inaccurate documentation may as well not exist. It doesn't provide helpful information. It wastes time, sends users down the wrong path, increases the time developers must spend supporting their projects, and breaks any semblance of trust that may have been established with the reader.
Ensuring that documentation is readable is crucial, but verifying its accuracy is equally important.
To ensure accurate documentation, a series of technical reviews with the original feature developer should be performed throughout the process. The first review should occur before any documentation is written. This gives the writer time to understand the necessary information before putting it on paper.
After the initial draft is written, a second review should be performed to verify the accuracy of the written piece. This ensures documentation is written from a new user's perspective while allowing clients to correct any misunderstandings or assumptions before publishing.
The final trait of high-quality documentation is discoverability. It doesn't matter how accurate or readable documentation is if the user can't find the information they're looking for. Discoverability can be accomplished in several ways.
Establishing an intuitive and browseable information architecture is vital to making documentation discoverable. It's the minimum requirement to enable readers to find the information they need about a given feature. A simple way of accomplishing this is establishing a set of topic-based hierarchies to categorize documentation. For example, Dashboard → Account → Account details.
Identify gaps in your documentation structure (or information architecture). Plan your documentation structure around the user journey — think about what the user needs to see and the logical progression they take when looking for answers in your docs.
In addition to establishing an information architecture to organize documentation better, it's essential to put some focus on usability. Usability, in the context of documentation, means structuring single-page documentation with ease of use in mind. Little things like syntax highlighting code snippets, descriptive animated GIFs, and a “More info” section can make documentation easier to read and parse.
Indexing documentation and providing a mechanism to search it can make up for any failings in the other two categories. Search is the most common definition of “discoverability.”