Types of Reuse

Scenarios of reuse

There are four scenarios within which reuse can occur:

• Same content published in different media
• Same topic in different documents
• Same content within many topics
• Slightly different content within one topic

The first is very elementary, for example, outputting the same document as a chm, web help, and as a PDF. This is the equivalent of changing the paper in the copier from canary to goldenrod while running the office Christmas party flier and saying you are reusing content. Not very interesting and I'm not going to talk about it.

Same topic in different documents

The next scenario, using the same topic in different documents, is perhaps the most common and most efficient way to reuse content. There are a few requirements to reuse content in this way:

You must write modular, stand-alone topics. DITA and Information Mapping are both good models for writing modular topics. The usual restrictions apply:

• No transitions from or to other topics, such as, "As we said earlier..." or "In the next section..."
• No restrictive references that limit reuse
• No embedded links that create dependencies with other topics

The first two requirements fall on the shoulders of the writer. Avoiding transitional phrases is easy enough; it's the need to avoid restrictive references that requires foresight and new sensitivities. For example, many writers would write, "Click Configure > Firewall > Access in the navigation pane on the left," without a second thought. On second thought, however, that navigation pane might end up on the right if the UI is localized for Arabic. You can't just hope the translator would know that. Other restrictions might include mentioning specific products in a topic that might be applicable beyond the product you're writing for. For example, the conceptual topic "How Access Rules Work in the Sentry 2X" might also apply to other product models as well, so the title "How Access Rules Work" would be less restrictive. If the reader is in a document called "Sentry 2X Configuration Guide" she won't wonder if the topic applies to her.

The third restriction, including links that create dependencies, is similar to the second, avoiding restrictive references. I separate them because your composition tool can help in the case of links. In DITA, for example, the link between Topic A and Topic B is not coded into Topic A or B. That relationship is defined in a ditamap, a third file that exists independently of the the two topics. This enables a writer to take Topic A and not have to take its link to Topic B (meaning the writer is free to take A and not B). If you are serious about reuse, you need to have a composition tool that lets you define links independently of the topic content.

Use ubiquitous graphic formats. The best format for graphics is .jpg if you wish to maximize their reuse across multiple media.

Be able to save the topic as a standalone file. Essentially, this establishes the portability of the topic. And while we are on the subject of files, get used to naming your files in all lowercase and without spaces. All operating systems can deal with that convention, whereas some cannot handle mixed case or spaces.

Pull discrete files into a document by pointing to them. Your system needs to build documents using structure files, that is, files that define what content to include, but do not contain the content itself. In DITA, this is done with a file called the ditamap. It points to topics and other ditamaps, defines sequences of topics, any parent/child relationships, and can contain relationship tables to define how topics link to each other within the context of a particular document. Metaphorically speaking, it is the blueprint that makes a particular set of content legos a Ferris wheel and another set (including many of the same legos) a firetruck.

Next blog we will discuss using the same snippet of content across multiple topics.