Discoverability

Photo by Mediamodifier on Unsplash

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.

--

--

--

Technical writer for AWS. I enjoy documenting my thoughts and sharing ideas with others.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

To Read This Month — June 2020

A Skeptic’s Guide to Design Sprints

The Future of Graphic Design

The five most damaging hotel website design mistakes - and how to fix them

Mental Models for Product Design

As someone born and raised in a single family home with a trim lawn in the white suburbs of…

Web trends for 2017

Kindness in Design Thinking

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Patrick Rachford

Patrick Rachford

Technical writer for AWS. I enjoy documenting my thoughts and sharing ideas with others.

More from Medium

This boomer insists we have sacrificed privacy for convenience to our detriment.

5 Tips to set up your software research profile

What I Learned from Interning in Factory Software at Tesla

How creepy and dangerous technology can be?