Solving the copy/paste problem with DITA topics

As a content author, you probably re-use a lot of the same material across different documents. If you work at a company that provides website hosting, you probably can re-use entire sections of documents for the "onboarding" guide, the "new user" welcome kit, and the "getting started" website for new clients. Once you've written the section on "how to login to your web server" for the "onboarding" guide, you don't need to write that a different way for the welcome kit or "getting started" website. No one has the time to rewrite that. Instead, it's easier to copy/paste the content from one document to the next.

But the more we copy/paste between different documents, the easier it becomes to lose track of the latest version. Let's say you copy the "login" section from the onboarding guide and paste that into the welcome kit. At the same time, you realize you can make a small edit to improve the flow. Later, you copy the content from the welcome kit into the "new user" website, and again you make a small edit to the text. Now you have three slightly different versions of the text.

When you create your next document that needs to re-use the same content, will you remember which document has the most up-to-date version of the text?

The solution is topic based authoring. With topic based authoring, you can capture documentation as separate topics and work on them as individual units. Later, you can string them together to create completed documents or transform them into other formats such as ebooks or websites.

Getting started with topic based authoring takes some practice. Here are three lessons I've learned in the year as I've migrated documentation into a topic based authoring system:

1. Divide and conquer

The key to topic based authoring is to separate each unit of information into its own topic. Look for natural divisions in the text to suggest where you can separate blocks of content into a separate topic. Document sections are one way to break apart documentation into separate topics. Also look for content that answers a particular question or provides a how-to. These are also good candidates to split a document into separate topics.

2. Leverage the topic types

You can use DITA to capture the different topics. DITA stands for the Darwin Information Typing Architecture (DITA) and is defined by the OASIS group (Organization for the Advancement of Structured Information Standards). DITA files are XML files, which means they can be translated across different platforms and software applications.

DITA offers several topic types for storing information:

1. DITA Concept: Information about a thing or process.
2. DITA Tasks: Steps to follow a process.
3. DITA Reference: Just the facts, such as a table of technical specifications

As you divide content into separate units or topics, consider what kind of DITA file you should use to store that content.

3. Keep content organized

If you use a DITA tool (and there are several options available to choose from) that tool will also include some level of project and file management, such as a recommended folder hierarchy. Consider in advance what organization will best suit your workflow. One way to organize topics is to store all DITA Concepts in one folder, all DITA Tasks in another folder, and all DITA References in a third folder.

But this can become unwieldy if your project grows to contain a large number of topics. Look for other ways to separate content. If you write user manuals for a company that assembles bespoke golf carts, each golf cart is likely built from a set of stock parts. So you might organize topics so all steering wheel topics go into one folder, all engine topics go into another folder, all seat topics get stored in another folder, and so on for every component.

DITA and topic based authoring can be a great solution to the copy/paste problem. Avoid copy/paste between documents by moving your technical writing workflow to topic based authoring.