The Relationship Between Structured Content, Topic-based Writing, and Single-source Publishing Produces Heroic Results
Creating good technical content can be an adventure fraught with danger. But do not despair, for there are some brave heroes who will fight for you! Call them the Three Musketeers of Technical Content, and learn how they stand together to do good for the kingdom.
Structured content, topic-based writing, and single-source publishing are the Three Musketeers of technical content. Together, they introduce flexibility, usability, and efficiency into creating, maintaining, and publishing technical content. When the Three Musketeers join forces, often using a model such as DITA, you can realize significant, measurable improvements in your content’s quality. You’ll also be able to be more versatile with your publishing—publish on demand and to the outputs you want (like mobile), while also streamlining your entire production process. That’s what we call a win-win.
In short, your content value goes up and your costs (measured in time and effort) go down, a condition that corporate royalty may actually recognize and reward.
The First Musketeer: Structured Authoring
Athos, the venerable and wise musketeer, used his experience to guide his efforts. In much the same way, you can use structured authoring—the application of XML (or SGML if you’re old school) tags to your content—to mark it up in a semantically meaningful way. For example, all notes would be wrapped in a <note> tag. You can then centrally and universally format all note tags to display in a certain way when published without the author ever having to do anything more than wrap the note in the <note> tag. Structured authoring separates content from format, which means you can update formatting centrally, increase consistency, and author more quickly.
- Structured authoring example: code view of a note.
Structured authoring example: the same note viewed with tags on.
Structuring content also introduces the ability to leverage metadata, which can be used to control the format of content (you can use metadata to differentiate a generic note from a warning and automatically apply different formatting), filter based on conditional properties, include SEO terms, add subject categories to browse by, leverage content for re-use, and about a million other uses. Metadata is like a Musketeer’s weapon—it’s an extension of the musketeer and it can be used in a myriad of different ways. I also like to think of metadata as a handle—once you have a handle on your elements, you can then fling them this way and that and get your content to do exactly what you need.
Once your content is in XML, it is highly transportable. You can send it as XML to partners or OEMs so they can re-use it or publish it as their own (rebranded) with very little effort.
For a great explanation of markup languages, see David Farbey’s May 2013 online newsletter.
The Second Musketeer: Topic-based Writing
Porthos, the extraverted Musketeer lived life with gusto. Topic-based writing is a way of authoring content in small chunks, called topics. It’s a shift from chapter- or narrative-based writing, where you have a linear progression of content from page to page. Instead, in topic-based writing, you have individual, discrete topics that are focused on a particular purpose or goal.
The result of good topic-based writing is a smorgasbord of highly usable content (users can easily find and follow the topics they need). It is also highly re-usable content—because content is chunked into topics, if I want to use a topic in different places, I can. For example, you might want to include a topic about restarting a service in a set of Troubleshooting topics, in a Getting Started section, and in an Administrator’s Guide. You would re-use the exact same topic in all those places (no copy/paste!).
To understand more about topic-based writing, see Getting Started with Topic-based Writing.
The Third Musketeer: Single-source Publishing
Aramis, the wily and versatile musketeer, had the skills to manage intrigues for the best result. Single source publishing—using one source of content (one set of files) to create multiple output types (PDF, HTML, PowerPoint, Excel, ePub, HTML5, .chm, etc.)—provides a path to managing content more efficiently.
Single sourcing can also mean that content that is identical or nearly identical exists only once in the source files, but is published as many times as needed in as many output types as needed. This is also, more traditionally, called re-use but it has a distinct impact on single sourcing.
For example, you might have a standard warning about electrostatic shock in 200 places in your documentation set, but it exists only once in the source files. When you need to update it, you only have to modify once and it’s updated in all 200 spots it is used times all the outputs you publish to. That could be thousands of changes in roughly 2 minutes (to update the one place in the source file) plus the time it takes to publish. You can also streamline translation using single-sourcing. And from the quality perspective, it also means that inconsistencies never creep in. There are no variations (unless you want them).
How the Three Musketeers of Technical Content Work Together
- Structured authoring is the smart musketeer: It lets you leverage content intelligently.
- Topic-based writing is the devoted musketeer: It lets you focus your content on user goals and enables you to re-use chunks of content where needed.
- Single source publishing is the versatile musketeer: You can publish faster and to more outputs.
The three musketeers together are a powerful combination, where each part enhances the abilities of the others.
Once you create content in XML, you greatly enhance your ability to publish to various outputs. For example, because all your content is wrapped in semantically appropriate tags, you could publish mobile output that is a streamlined version of the full output by simply omitting certain tags (like a result of a step or the context of a task).
When content is in XML and written in topics, you can maximize your re-use of content easily and efficiently. You can also start re-using content on a sub-topic level: titles, phrases, notes, lists, steps, interface labels (like buttons or menu options). Honestly, that’s just the tip of the sword: You can start automatically creating supertasks (a high-level task where each step is an entire task in and of itself); you can include glossary popups inline where the popup is automatically inserted from a glossary topic; or you can automatically link content together. The ability to automate these things is where you realize great benefits.
Pros and Cons of Implementing a Complete Solution
As with any fundamental change of how you create and manage your content, there are pros and cons to moving to a structured, topic-based, single source publishing content lifecycle. This kind of complete solution involving structure authoring, topic-based writing, and single-source publishing (using DITA or something else), has some downsides and some upsides to consider.
Conclusion: All for One, and One for All
You can engage any of Three Musketeers, Athos, Porthos or Aramis, individually. Structured content without topic-based writing results in an XML model like DocBook. You can write topics without applying XML and still reap the usability benefits of targeted content. You can single source publish both without using XML and without writing topics (to a degree and with a specialized tool).
However, combining these Three Musketeers together in an “all for one, one for all approach” is like putting them all on performance-enhancing drugs. Together, they can do more, realize more savings, be more efficient, and have more versatility. In the end, the user gets D’Artagnan, their hero of great, usable content that is findable, responsive, and willing to go that extra mile.
Resources
- Farbey, David. Marginal Notes Quick Guides: An Introduction to Markup Languages. http://us6.campaign-archive2.com/?u=13b45a4440e7a661357ae956b&id=4694a05a76, downloaded 5/26/2013.
- Samuels, Jacquie. Getting Started with Topic-based Writing. TechWhirl.
- Content Structure Research Portal, TechWhirl.
