Discoverability
Discoverability is the most significant and often overlooked aspect in creating great documentation.
In this article, I will describe discoverability and methods used to increase the degree in which your documentation can be found.
The most significant aspect of documentation is discoverability. If your product’s users are unable to find your documentation or navigate throughout it, it won’t matter how much time you’ve spent managing and producing content.
The why on discoverability
Getting your users to find content they need on your web page is an often overlooked skill to improve your documentation. This article outlines two major pieces of discoverability that technical writers should focus on when designing, implementing, and managing technical documentation.
Navigating to your documentation
Search engine optimization (SEO) is a method to improve your web pages’ index scores on search engines like Google or DuckDuckGo. SEOs use algorithms to analyze pages and rank them based on a variety of factors to determine the order in which pages are listed on their search engine’s page. There’s an entire industry used to support SEO, so technical writers don’t need to be experts in SEO to increase their indexing; however, the following tips should be used to improve your SEO and, in turn, increase your documentation’s discoverability.
Some methods to improve your SEO include:
- Accurate titles and subtitles
- Thoughtful URLs
- Provide metadata and tags
Accurate titles
Accurate titles and subtitles will improve how search engines identify your documentation’s subject through the search engines’ web crawler, also known as a search engine spider. Focusing on the title of your documentation to encapsulate the main idea and the subtitle on what your users will want to look up helps your users interact with search engines and your documentation.
Thought URLs
Thoughtful URL names will increase your documentation’s indexing. If your walkthrough describes how to set up a Cloud Instance, you wouldn’t want your URL ending in a random string of letters and numbers. Instead, set your URL to /your-first-cloud-instance or /create-cloud-instance.
Metadata
Depending on your authoring language of choice, you should be able to set metadata or meta tags that accurately describe your page. Metadata enables you to choose how the search engines’ web crawler reads your web page. You’re able to set the description of your webpage. I like to think of writing metadata as the thesis of your web page. A short sentence or two that accurately describes what the reader can find.
Navigating in your documentation
Table of contents
The implementation and design of documentation is an important piece of discoverability. Knowing how your readers will browse through your set of documentation takes time, feedback, and continuous improvement. Starting off with a well-thought-out Table of Contents will give your users an understandable workflow and allow them to manage knowledge that applies to issues and learning.
Some ideas to keep around when implementing your table of content are:
- Accurate titles
- Collapsible content
- User’s workflow
Accurate titles
How you label your titles in your user guide will give the blueprint to your user’s ability to navigate throughout your documentation. Creating clearly labeled titles or headers will allow your users to quickly browse through topics, finding the most content pertinent to them.
Some examples of accurately labeled titles include: Introduction, Getting started, How to …, and release notes. Users understand these documentation conventions, and adding them to your user guide allows quick access to information.
Knowing who your users are and what they need in your user guide will allow them to better navigate your documentation set. Studying your users and which content they require will allow you to refine your documentation and give your users the best content experience.
Collapsible content
Collapsible content is an easy way to group similar content under a major heading, however, this can create accessibility issues. Screen readers have improved to help common design structures used to organize and hide content, so as not to overwhelm the user, known as accordions. Nesting content 2 or 3 accordions deep will add complexity to users with accessibility issues, as well as others who can’t find your content.
As your user guide grows, and you add more topics, you may need to readjust how your content is organized and presented, so you can give your users the ability to navigate throughout your documentation set.
User’s workflow
Understanding how your users interact with your documentation and their managed workflows will create a better relationship between your documentation and end users. Some user guides will need a concept page before walkthroughs, if you’re introducing abstracted language or complex ideas to your users for the first time.
Consider your user’s workflow and understand how they interact with the product you are documenting will help you make decisions related to the flow and order of your documentation.
There are many aspects to discoverability, and no one size fits all approach will work. Understanding your users and improving your documentation based on feedback will increase Discoverability and allow your users to actually use your product with its documentation.
Let me know in the comments below how you improve your documentation’s discoverability. Thank you for reading.