Many companies produce user documentation and training materials for their products. The problem is that documentation and training materials are often similar, so producing them separately wastes effort and resources. Is there a way to make the process more efficient? Of course.
The most efficient process is to create the content in chunks that can be shared by the doc group and the training group (and perhaps other groups as well, such as support or marketing). Modern content authoring solutions such as MadCap Flare and MadCap Central from MadCap Software offer this capability in varying levels of granularity. These levels range from:
● Topic: A chunk of content that describes an idea or task in its entirety. For example, how solar cells work or how to set up a furnace to melt germanium to manufacture solar cells. Topics have been with us for years. Any author who creates technical documentation or is familiar with single-sourcing works with them.
● Snippet: A chunk of content that describes one element of an idea or task and is likely to be used in multiple places, such as within multiple topics. For example, if the same dialog box appears in multiple places in your software, you could write a description of the dialog box with a screenshot and explanatory text and insert that material as a unit into multiple topics. What’s still more helpful is that making a change in the content of a snippet can make that change in every insertion of that snippet, which can save many hours of work.
● Variable: A chunk of content similar to a snippet but shorter and limited to text only (no graphics, tables, or so on). Variables are used for pieces of information that may change, such as the name of a new product whose prerelease and release names are different or a company whose name may change as part of an acquisition.
● Microcontent: A chunk of content that exists itself or that can be extracted from a topic. These typically short chunks of content can then be displayed to show only the most relevant information in response to a search. For example, users who search for the phone number for technical support just want the phone number without address information. Microcontent provides that level of granularity.
As useful as these features are by themselves, the use of conditions takes them further by letting authors turn these features on or off based on what are effectively business rules. For example, authors might display snippet number one in output for an audience in the United States but snippet number two instead if the audience is in Canada. Or perhaps change the wording of a step depending on whether the output is for online delivery versus printed documentation versus printed training material.
And as useful as these features are by themselves, they’re made even more so because they can all be applied to one body of content. That collection of content can be put into source control to be maintained by multiple writers in multiple departments, such as the doc group and the training group, for a more balanced workload.
As good as all this sounds, one huge issue must be dealt with on the management side: setting standards. While authoring solutions can be set up to control wording automatically using conditions, snippets, and so on, this can only go so far before the project becomes too complex to understand. This puts much of the onus back on the human side. Project team members, especially those from different departments, must agree on standards for things like terminology, spelling, the writing grade level, when to break material into topics, and more. And, the whole thing—the technical aspect as well as the standards-setting—has to be documented. Without that, there’s a good chance that all the work will be lost when the current project team members leave. In the past, these standards were typically documented using Word, if at all, but solutions like MadCap Software offer built-in project management features and features that can be adapted for project management, such as comment tracking and electronic reviews, so we have the tools needed for project control.
About The Author
Neil Perlin is the president of Hyper/Word Services, an online content and app development firm based in Vermont. Neil is MadCap-certified in Flare and Mimic and a frequent speaker at MadWorld and other industry conferences. You can reach him at nperlin@nperlin.digitalspacemail8.net or follow him on LinkedIn, Facebook, or Twitter (as NeilEric).