How to evaluate documentation

At the end of each section, I include a list of questions, relevant to that principle, that can be used to interrogate a text. I include them here in a consolidated way for convenience:

Questions for letting users switch between macro and micro views

• Can the process be simplified by chunking the information into more granular steps?
• If there are multiple chunks spread out that users have to follow, is there a map that connects the chunks together in a navigable way?
• Would it be appropriate to provide a quick reference guide of the process, as a high-level map of the information terrain?
• Does each chunk connect to the next with a “Next Steps” section?
• What larger process does this task fit into?
• What mechanisms facilitate zooming in and out of the process?
• If you were to draw out the process, what would the workflow map look like?

Questions for making information discoverable as the user needs it

• How will users discover this information?
• Is the topic SEO friendly for keywords that users would target?
• Are there places in the UI (or in error messages, etc.) where we could link to the topic?
• Could this be a related topic in other areas where users might end up, such as on other topics (as they follow the information scent in the docs)?
• What metadata attributes should this information have (audience, location, operating system, device, language, etc.)? How can we map this metadata to the user to surface this content more naturally to the user’s context?

Questions for ensuring information harmony in the larger landscape

• What else has been written about this topic on our site?
• What has been written about this topic on other sites?
• What do users see when they search for these keywords? Do other articles on our site appear beside this article?
• Does this article contradict, repeat, or harmonize with the other information about the topic?

Questions for reducing and distilling vast information down to its essence

Some questions you might ask of a text include the following:

• Is there a high-level summary at the top of the document?
• Is there a mini-table of contents in the document?
• Are the headings descriptive of the content, allowing users to consume it at a glance?
• Have you stripped away or hidden the non-essential information that users might consider extraneous to their core tasks?

Questions for conforming to the patterns and expectations of the genre and schemas

• Does the topic contain these categories: goals, prerequisite states, action and reaction, unwanted states (and troubleshooting)?
• Does the discourse follow a task-based format for the genre?
• What story are you telling? Is your content structured around that story?

Questions for reconstructing the absent user

• Who is the user? What do you know about the user? For example, what are their goals, what’s their technical level, what are they building, how are they reading your information, what language do they speak fluently?
• What do metrics tell you about how users are interacting with this content?
• Are you capturing any feedback about this content based on your feedback mechanisms?
• What kind of support tickets have been filed against the topic?
• Can you reach out to a target group of users to gather more information about their experience with the topic?

Questions for reducing the complexity of technical language

• Are you using the right technical terms?
• Do these technical terms align with the same terms used in other documentation from other companies on the same topic?
• Are the terms defined?
• Is there any background reading users should do to ramp up on the topic?
• Do you use terms consistently or do you include synonyms?
• Could some of the language be made more accessible through tooltips?
• Are you using plain language to reduce the jargon and technical complexity as much as possible?

Questions for aligning the product story with the user story

• What is the story of your product that your company is telling?
• What story is your user following in their mind?
• How do the two stories overlap? What common ground can you use in the user’s story to make your product more relevant?
• Are you developing features in your product that align with the user’s story?

Questions for iterating and incrementing on content following an agile approach

• How many iterations has the content been through?
• What input are you using between each iteration?
• How are you collecting feedback about content?
• How many different perspectives can you incorporate to gather input through each iteration?

Questions for hiding complexity with UX design

• How can you reduce the scope of the content by hiding the unnecessary (or less essential) parts of information?
• With progressive disclosure in mind, how many levels should the information flow?
• Can you reduce the complexity of information by hiding some parts or making it more navigable through JS or other techniques?