Best Practices for Content Reuse

Update: Originally this post was titled Some Suggestions for Content Reuse. I’ve since changed it to Best Practices for Content Reuse because I’m a sucker for arguing with my fellow tech writers about what constitutes a best practice.

Content reuse is the process of writing a piece of content once and inserting it in many places; then when you need to update the content, you need only update the source, and the changes will cascade to all the copies.

It’s a great idea. If you have ever found yourself writing the same sentence or steps over and over again across multiple documents, of course you would rather reuse that bit of content elsewhere without having to copy and paste it; without having to manually re-type it; without having to edit multiple places if and when the content changes. Tools like Atlassian Confluence, MadCap Flare, Arbortext Editor, and Adobe RoboHelp all come with features that let you achieve this goal.

But wait! Content reuse is more difficult in practice than it sounds. Here’s why:

• Naming: When you create a piece of reusable content—what people often call a “snippet”—you need to give that snippet a unique name that other people who aren’t you will understand so that they, too, can reuse it.
• Storage: You must place the snippet in a location where other people who aren’t you can find it.
• Duplication: You must make sure that other people who aren’t you don’t duplicate the snippet you wrote. If and when they do (it really is only a matter of time), you must work with that person to merge your snippets together, or choose one instead of the other, and update things to use the snippet of choice and delete the duplicate.
• Context: You need to know all the places where a snippet is currently being reused—or try to imagine where it might be reused at some point in the future. If you don’t, you might make a change that will look fine in one place and very strange in another.
• Scale: You need to have a plan to manage (i.e., limit, update, refine, retire, etc.) the snippets you create. If you create too many, you could end up with tons of little fragments that are almost as difficult to maintain as not having created them in the first place.

Given these challenges, many technical writers avoid content reuse altogether. I do not blame them. Content reuse is one of those marvels of technology that can save a lot of time—if you do it well. Doing it well is hard. It is, in fact, an art that requires careful thinking and a heck of a lot of imagination, hands-on testing, and ongoing maintenance.

Best Practices

Here are some best practices to keep in mind if you are going to reuse content. Previously I called these “suggestions,” but so far I haven’t found much improvement upon these points. They are practices that I have seen or read about elsewhere at other companies, and/or that have worked for me in many years of planning, trial, and error.

• Use discrete chunks. Reusing content is typically easier to do if your content is broken down into discrete, relatively independent chunks. The more independent the information is—that is, the more it can stand alone without needing too much context—the easier it is to reuse on other pages. Often this will require you to rewrite your content. For example, avoid context-dependent words and phrases such as: “the image below displays…” or “the next paragraph explains…” or “In the introduction, we said…” Definitions of products or ideas or processes tend to be good candidates for this.
• Minimize content types. For example, avoid adding tables, headings, images, and other non-textual elements inside the snippet. These things make it more difficult to reuse the content in other contexts.
• Minimize formatting. Ideally your snippet would have little to no formatting at all. For example, avoid wrapping a bulleted list inside a snippet, because you may want to reuse the text from that sentence on other pages but not the bullet itself.
• Don’t get too granular. Avoid creating snippets at the level of individual words or phrases. In general the most granular you should ever get with a snippet is a single sentence. There may be exceptions: you may want to snippetize and reuse a heading. But imagine how complex that could soon get. You could be tempted to snippetize scores of headings that appear throughout your docs. Try to avoid those situations and restrict the power of snippets to sentences and paragraphs. I think this is wise because sentences change more often than headings and thus tend to be more difficult to find and replace.
• Define a maintenance strategy. If you end up using lots of snippets (fifty or more, for example), create a strategy for how to write and maintain them over time. Here are some ideas to that end:
  • Define a policy for when to create snippets—and when not to. To this day I have not found a foolproof set of criteria. On my team we generally say to snippetize something that you find yourself copying and pasting at least twice. But that is not the greatest solution. What if you only ever use a snippet in two places? Is it worth the overhead of maintaining that snippet? What about three? Where do you draw the line? I honestly don’t know. If anyone reading this does, please leave a comment and give me the magical spell.
  • Create a naming convention for your snippets and categorize them in different buckets. For instance, all our conceptual snippets begin with conc-SnippetName, while all our task-level or step-level or cross-reference snippets begin with task-SnippetName, step-SnippetName, and xref-SnippetName respectively.
  • Create a standard library structure for your snippets. This is a more complex endeavor, and it runs into maintenance problems of its own. But it will be precisely what you need as your snippet library grows. For example, you might create snippets by product, and then enforce a naming convention for the snippets that get stored within that bucket.

Of course, these “best practices” are not universal by any stretch; you will need to tailor them, and it will be important to exercise restraint when doing so. If you find yourself in situation where you have over a hundred snippets to manage, the maintenance overhead grows exponentially. This is especially the case if your snippet library grows organically with little to no oversight or long-term strategy. That is one reason I have become less enamored of snippets in my old age, and more in favor of hyperlinks. Ask yourself whether you really a need a snippet or if you can solve the problem by writing a summary which then links to another page with details. Give it thought, use your imagination, test it out. What you should not do is rush the process or dismiss it as simple and benign.