Say Goodbye to Narrative Writing
Traditionally technical writers prepared documents—books and sections of books to explain how to work with the technology being presented—and it worked fairly well. Today, authors must deliver content designed for quick consumption a whole array of media. And authors working within Darwin Information Typing Architecture (DITA) must shift their thinking about the content writing process itself. Because within the DITA model, you no longer write books or even chapters. You write topics.
DITA topics vary in type and in length, but they all share one thing: every topic must be able to standalone.
- A topic might be inserted in any location by you or someone else.
- A topic might be read completely out of order from the topics around it.
- There is no preamble or setup for a topic.
- There is no content that glues topics together; every single sentence is inside a topic.
This shift from narrative-based writing to topic-based writing challenges authors but it adds a great deal of flexibility to your content. Topic-based writing leads to more usable and more re-usable content. Once content is chunked into topics, it becomes more easily findable and more easily consumed.
Change the Structure: Write within the DITA Architecture
The DITA architecture itself changes your writing in three main ways:
- Topic types: Write for the three main topic types
- Topic architecture: Write each topic according to the DITA rules
- Cross-reference elimination: Cross references here, there, and everywhere are no longer a good thing.
Topic Types
The three main topic types in DITA make sense to most people. And, when you write a topic, it must be one of the three types:
- Concept: Explanation of what or why
- Task: How to perform a something to reach a goal
- Reference: Quick look up information
DITA includes other types, like glossary and troubleshooting and a whole set of learning and training topics, but for the most part, your content will fit into the three main types. For example:
| Concept | Task | Reference |
| Architecture of the product | Set up environment variables | List of commands |
| Feature overview and benefits | Send content for review | Configuration options |
Authoring in the DITA model is most challenging on those occasions when content is too complex to fit neatly into the topic types, such as complex installation and configuration content. You have two options in these circumstances:
- Re-write the content into chunks and use hierarchy in the maps to stitch it together (there are various mechanisms available to help you out).
- Simplify the product.
The option you should never take is forcing content into the topic types even if it doesn’t fit. This is called tag abuse and leads to more re-work down the road, often after a lot of wheel-churning trying to publish such badly tagged content.
Topic Contents
Each topic type has specific elements that are allowed in a specific order. For example, every topic must begin with a <title> element. You cannot have a sentence before the title. Every topic should then have a <shortdesc> element, which briefly gives the user an idea of what content is covered in that topic; this is a piece of content that enhances but does not duplicate the title.
You then get to the core of the topic, which changes based on the topic type you are writing.
The most restrictive topic in terms of the order of elements is the task. For example, if you have a pre-requisite and a context (why a user would perform a task), then the pre-requisite must come before the context. Similarly, the post-requisite (if you need one) must come last. If you try to change the order of these elements, you will create a file that is not valid and cannot be processed into an output.
How does DITA change Authoring? You write topics rather than chapters, according to topic type and a structure that supports reuse.
Although some authors find this initially confining, the standardized result is well worth the effort of matching your content to the DITA architecture.
Cross Reference Elimination
Although the DITA architecture allows cross references, using them creates a dependency between those two topics: if you include one topic in a deliverable, you must include the other as well.
You can see that it wouldn’t take long for the addition of cross-references here and there between your topics creates a nest of dependencies. The effect of these dependencies is that you are prevented from reusing topics independently of each other, one of the major benefits of DITA.
DITA includes a mechanism called a relationship table that allows you to create links between topics without creating dependencies. The relationship table is part of the DITA map, rather than of the topics. Any link between two topics created as part of a relationship table is simply listed at the bottom of a topic, not inline (in a sentence or step).
Authors have been so dependent on using cross references to provide more information that they are often loathe to give them up despite their obvious drawbacks.
It takes a confident author to write enough information without either overwhelming the user or needing an inline cross reference. In fact, it usually takes some training and support from experienced DITA authors.
Change the Approach to Content: Minimalism and User-Focused Content
Although not strictly part of DITA, minimalism and user-focused content increase the quality of DITA content so much that they tend to be implemented at the same time, with impressive results.
Minimalism is the art of providing just the right information in the right spot to increase the usability of the content and cut away all the noise. It’s more than just removing information, it’s focusing the content on just what the user needs to get their job done.
Summary
When you adopt DITA in your organization, expect your authoring to change in some profound ways, but those ways will vastly increase the usability and flexibility of the content. With solid training and ongoing support through your DITA adoption, the changes to your writing will become second nature within a few weeks.
