What makes a good feature guide?

Feature guides are a staple of software documentation. But what makes a feature guide a good feature guide?

What is a Feature Guide?

Let's begin at the beginning. What do I mean by feature guide?

A feature guide is a manual-style article that describes a product feature for a theoretical user.

Feature guides are an obvious necessity in software documentation. Feature guides help prospective customers learn about your software, as well as help customers get started using your tool. 

What Makes a Good Feature Guide?

So, what makes a good feature guide? I looked through my content and identified the feature guides that have either the highest traffic and/or the highest ratings. I also went through the feature guides for some of my favorite software documentation. I identified the below features that are common to all good feature guides. 

Good Introductory Content

For starters, a feature guide must have informative yet concise introductory content. Below are some characteristics of a good feature guide introduction.

Answers To the Essential Questions

The two questions that must be answered in a feature guide introduction are:

1. What is the feature?
2. When would a customer use the feature?

If you can answer these questions in two sentences all the better. The introduction should serve as merely a signpost letting the reader know they're in the right place. 

For example, below is the introduction to a new question type we just built at SurveyGizmo:

Conjoint is a market research question used to determine how customers value the various features that make up an individual product or service. Use the Conjoint question to determine what combination of features is most influential on customer decision making.

Examples

When necessary, your introduction may need to include an example use case. If there is a chance that your initial content written to answer "what is it?" and "when you would use it?" might not be enough for the user to understand then an example use case should be provided in the introduction. 

Definitions

If there are terms that are essential for understanding a feature, definitions of these terms should be provided in the introduction. 

Here is an example of a glossary term that is highlighted in the introduction of one of my feature guides.

An Image That Demonstrates the Feature

Finally, if it's possible to convey the feature in a single image or possibly an animated gif include that in your introductory content. This serves as another signpost to let the reader know they're in the right place. 

Here is an animated gif, I included in SurveyGizmo's question logic feature guide to demonstrate question logic in action.

Easy-to-follow Setup Steps

Once you've let readers know they are in the right place and you've given them the essential tools to understand the feature in your introduction, you're ready to jump head-first into setup steps. After all, that's what you readers are looking for. 

When writing steps to setup a feature be sure not to skim over prerequisites. Often the use of a feature depends on having other features setup. Begin your setup steps here. You can cover the steps of the prerequisites in your feature guide or simply link to the article that covers them; just be sure not to forget about them altogether!

I've also found that readers prefer numbered steps. This can take many forms, interestingly. Using strictly ordered lists can lead to very long articles. I usually eschew the ordered list for style and space saving reasons. 

Common Customizations

If there are common customizations users typically wish to make to the feature it is best to include this as its own section in the document. 

Putting this content under its own header helps to ensure that readers find this content. 

Collect Feedback and Iterate

Once your feature guide is written and published your job has only just begun. The best feature guides are iterated on. Collect feedback from your readers to learn how to improve your content.

Add FAQs and Tips

As readers ask questions consider adding these questions and their answers to a FAQ section in the article. 

Users will also often tell you where they got hung up. Use this valuable information to improve your content. I often add tips throughout the setup steps to prevent other users from getting stuck. 

Move Beyond the Feature Guide

In a previous post, I argued that feature guides, while necessary, do not do a great job of answering users questions. In addition to iterating on the feature guide itself with tips and FAQs, you should also create new articles to get users to an article with answers to their specific questions. Not sure how to go about this? Check out my previous posts on Just-In-Time Documentation and Using Search Terms to Better Answer Users' Questions!