Structured Writing Part 3: Tools
Structured writing is not necessarily dependent on a tool, other than a writing program, if you have a simple scenario like creating a letter in Microsoft Word. However, structured writing is often used in more complex scenarios, such as if you have hundreds of topics authored in an XML-based editor, like XMetaL. Since there are a wide range of scenarios, I’m going to focus on structured writing as it applies to reused technical content authored in XML using DITA, which does require tools. In this scenario, I’ll talk at a high level about the five main tools that are required.
1. XML Authoring Tool
You need an XML authoring and editing tool such as oXygen XML Editor, XMetaL or Arbortext Editor. These tools come with a range of capabilities and licensing structures.
2. Writing Architecture
DITA (Darwin Information Typing Architecture) is an open architecture for structured content. It allows you to label all the components of your content with predefined elements. While there are many different elements overall, the main elements for topics are task, concept and reference. For example, the topic of “How to Verify Package Contents,” which I used in my previous blog post on structured writing, is a task element. To use DITA, you first need to audit your content and then see how it fits into the standard. You can also have variations for cases where content doesn’t fit into the architecture. While there are other content models, DITA is the most commonly-used standard for technical writing and XML authoring tools come with DITA support.
3. DTD
A DTD (Document Type Definition) is a set of markup declarations that defines what structure is valid. For example, let’s say that we decide for tasks that:
- Every instruction needs a header.
- Steps must be in a numbered format.
If we write the task like the example below, with the instructions in a paragraph form, the DTD will recognize that the format isn’t correct and you’ll get an error:
How to Verify Package Contents
Open the box and find the packing slip. Make sure the contents match up.
The DTD validates the structure as you develop content so you won’t be able to do anything that doesn’t fit into the structure. Standard XML authoring tools come with a DTD. You can also create your own or modify existing ones, which you may want to do if you have specializations.
4. Style Sheet (XSLT)
A style sheet, or XSLT (Extensible Style sheet Language Transformations),
defines the formatting for each element and output type. Standard XML authoring tools come with style sheets but you may want to modify them to include your company’s style standards. For example, if you want to change the font of numbered steps to Calibri 11 point, you’d define it in the style sheet.
5. Component Content Management System
Unlike standalone documents, a document created in XML may contain tens or hundreds of smaller XML files, which are pulled together by creating a DITA map. All of these little XML files need to be stored and managed in a Component Content Management System (CCMS). Each file can be reused across many different documents and outputs. A CCMS manages the lifecycle of each of these files. There are many CCMS options with different features and costs.
Conclusion
The five main tools used in structured XML writing are an XML writing tool, a writing architecture such as DITA, a DTD, a style sheet and a content management tool. In the next blog posts in this series, I’ll get into more details about creating content for reuse using DITA.
