How Can Writers Build Better Online Help Experiences?

MadCap Flare help authoring

Although end users never articulate the true criterion for judging online help, i.e. Will they find the necessary answer before they lose patience, the rest of the documentation community operates to achieve this singular goal through information architecture, authoring tools and review processes. Therefore, in practical terms, the documentation group is left to try to maximize returns on efforts within given constraints.

We will focus on four key areas of value to online help and discuss each in turn. We will start with the decisions made around the authoring of content and then move on to how that content is reused, followed by an examination of the workflow used to manage documentation and finally how that documentation is measured.

Design topics around the task, not the interface

It is tempting to organize your online help around the same menu structure that you used for the product. However, the reader approaches your online help mid-task, usually after doing a search or clicking a link within your application. That reader is looking to complete a task. Name and scope topics for what the reader is trying to do.

Topics should have a single type. Concept topics can explain why something exists in your application, task topics can describe step-by-step processes, and reference topics can include tables, parameters, and limits. Combining these types of information on a single page is probably the most common structure mistake found in the help of mature applications.

Setting a minimum viable topic standard

  • One topic answers one question, stated in the heading in the reader’s words.
  • Prerequisites appear before the first step, never inside step three.
  • Any procedure longer than nine steps is a candidate for splitting into a parent task with subtasks.
  • Every topic carries metadata for product, version, and audience so filtering works later.

Make reuse structural rather than opportunistic

Copy and paste is reuse without a contract. It works for a short while and then breaks, usually because of a change in a legal disclaimer, the name of a product or function, or even the addition of a single step. The useful documentation reuse is stored in snippets or in reusable components, and is included in the content with the aid of a contract that defines the terms and conditions under which it can be used.

There is an important distinction to be made between content that can vary based on an author’s audience and content that is identical to be used by everyone. This identical content can be created as snippets or as reusable components that can be inserted into other documents as needed. Variable content, on the other hand, is typically used in conditional text or variables and is created to produce different outputs from a single source file based on how the file is built. As stated above, if you need that discipline enforced at the source level, a tool such as MadCap Flare help authoring is worth considering, since it and DITA-based systems enforce the necessary divergence to allow for the creation of reusable snippets and components.

Choosing a reuse mechanism

MechanismBest forMain cost
VariablesProduct names, version numbers, URLs, support contactsLow, but needs naming discipline
SnippetsRepeated warnings, standard procedures, boilerplateModerate, edits ripple to every instance
Conditional textEdition or audience differences inside one topicHigh, conditions compound and become hard to test
Separate topicsContent that diverges by more than roughly a thirdDuplication, but easier to maintain than tangled conditions

Knowing where to draw this line is critical, Documenting everything to condition based on build can result in source files that are not manageable by humans, while the build matrix will grow faster than your ability to review all the needed configurations.

Build a workflow that handles change, not just creation

Again, much of the effort in documentation is in the maintenance. So why do we design processes for the first draft? Treat your source content as code. Put it in a version control system. Branch for releases. Require review through a pull request or similar gate instead of relying on email attachments for review.

Connect your documentation workflow trigger to your engineering workflow trigger. Thus, if a ticket causes user interface changes, it needs a documentation flag which must be cleared by the writer before the ticket can be closed. This simple rule, which detects most writing for updates needed for new releases, saves the writer most of the time spent in tracking changes.

Review that scales

  1. Technical accuracy, from the engineer who built the feature, scoped to facts only.
  2. Task validity, from support or a product specialist, checking that the steps actually complete.
  3. Editorial pass, applied last, against a written style guide rather than personal preference.

Rushing both simultaneously leads to conflicting comments. Sequencing them this way only takes a day but can save a lot of back and forth in the end.

Measure retrieval, then fix what the data exposes

While it is nice to know how many times a particular page has been viewed by others, more useful signals to track are internal search queries that failed to return useful results, very high entry and immediately abandoned topics, and high volumes of support issues that could have been answered by documentation already written.

Use failed queries to build a list of synonyms to include in the search field, and apply the list to the field. Content that is duplicated by support issues most likely has problems with findability rather than quality, and this is usually a matter of title, metadata, and linking to the help content within the application rather than rewriting it.

Better help experiences are created by giving consistent structure to content, using disciplined reuse, and controlling changes in help topics themselves. None of these things need to be reworked. What needs to be worked out is which constraints to choose and how to enforce them for all topics.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top