FAQs vs. Solutions vs. User Guides – When to Use What
Product documentation is one of the best investments a software company can make. Yet many companies don’t realize it, don’t quantify it, or don’t know how to go about doing it.
Our team’s consultants have decades of experience in software organizations, process improvement, projects, metrics, and benchmarks. All of them agree with the above unanimously. Why? Because they compared costs, helped create documentation, participated in the education of customers, and have seen the results of similar projects over and over again. Many people in the software business, however, continue to treat product documentation as a secondary requirement or an after-thought—often for lack of information. The struggle with product documentation in young and old companies continues as a common and widespread issue.
We could say documentation problems come from many different sources. Some organizations believe that their developers are the ones with the required product knowledge but want to spend their time building products rather than documenting them. Others understand that services and customer support organizations are the ones responsible for product documentation. Some even believe that customers just “don’t read manuals.” As long as upper management as a whole don’t understand the issues and the benefits related to product documentation and put in place a structured plan do address it, teams and individuals inevitably start initiatives to, somehow, document at least parts of the products to try to save their own time or to help customers. These non-structured initiatives consume energy from the wrong people, deliver little benefit, and generate redundant and difficult to maintain documentation.
We will start from here. Not from the origins of the product documentation problems, nor from the different organizational approaches to solve them, but from the point where people start to create product documentation of some sort. Should customer support begin to develop answers to FAQs? Should software engineering produce guides to the new features? Or should the services team be asked to create a knowledge base with solutions that they have devised?
The basis required for organizational measures, investment prioritization, and even hiring, often comes from a fundamental element: the product documentation architecture. We know there are different opinions out there, but here are, in a nutshell, some definitions that will help many people find a way to solve product documentation problems. And perhaps get out of conundrums, such as: “we don’t document products because we don’t have time, or we don’t have time because we don’t document products?”
User guide, or user manual – This is the documentation that explains how your product works: its purpose, how it’s configured and operated, and how it should be applied (we’ll soon be writing about a good structure for user guides). Note that FAQs or a solutions base will not comprise content structured enough to explain these sorts of topics. These topics require deliberate design and logical sequences to help the customer build their understanding of the product and its application. This structure will also simplify training, browsing, and searching.
Solutions – One can look at documented solutions as a way to address practical scenarios of everyday life. A user guide may use examples of how to apply a product feature, but it cannot detail the many possible scenarios to which different feature combinations could be applied. For example, a user guide may explain how a billing system works, but it will not detail all possible scenarios, such as invoice cancellation, late-fees collection, or applied discounts. These scenarios may be better described in specific documents, created if and when they’re identified as a (potentially) recurring topic. At that point, the benefits of spending a couple of hours documenting a scenario are likely to save many customer support hours.
FAQs – Canned answers to frequently asked questions are useful to help customer support agents and allow customers to help themselves. However, if a user guide is not available as a base reference, FAQs tend to be used as a poor substitute. If no user guide is available, even the most basic topics also become frequent questions: What is this functionality for? Can I use it with such and such settings? How do I apply it? Is it available to me? And so on. Besides, FAQs don’t offer the structure required to explain complex concepts, thoroughly cover long subjects, nor allow effective self-study. Therefore, FAQs should be used exclusively to answer frequently asked questions, not to document a product.
Have your teams for product management, software engineering, customer support, services, and knowledge engineering agree upon the architecture of your product documentation. You will see how much easier it becomes to assign responsibilities, create a documentation project for existing products, or establish product documentation routines.
Agree with the above? Have a different opinion? Have a particular issue about product documentation and would like to exchange ideas? Lived an interesting experience? Please leave a comment! We will be happy to share more information and insights about this many times controversial topic.