Skip to content

Structured Writing Part 6: Publishing XML Content

Document Translation

Structured Writing Part 6: Publishing XML Content

Once you’ve created some XML content using DITA, you’re ready to publish the content to one or more outputs. The building blocks for publishing are the XML files, a DITA map and a style sheet. XML authoring programs offer a range of publishing options. Let’s look at how this works.

Assembling the Content Using a DITA Map

To assemble the XML files, you need to create a DITA map in your XML authoring program, which is a way to pull all the XML files into an organized group. A DITA map is like a table of contents in a Microsoft Word document, only you’re creating it from multiple files. In this example, the DITA map for Output A would include topics 1, 2 and 3. The DITA map for Output B would include topics 1, 3 and 6.

You can add and delete topics at any time in a DITA map and you can have multiple DITA maps that make up a document.

Publishing Content

Once you’ve assembled your content in a DITA map, you can publish it to multiple outputs simultaneously, depending on your XML authoring tool. Some of the standard outputs include PDF, EPUB, Kindle, HTML and online help systems.

If you’ve created some conditional attributes for things like product, version or audience, you select these options during the publishing step. For example, in my previous blog post, I gave an example where three products all had the same instructions called “How to Verify Package Contents.” A fourth product had an additional instruction. To add the variation for the fourth product, you’d apply the product conditional attribute to the specific element that includes the additional instruction. Then when you publish the fourth product’s instructions, you’d select that product in the conditions option. The results would look like this:

Products A, B and C Product D
How to Verify Package Contents

Verify the package contents before you begin.

  1. Open the box.
  2. Find the packing slip.
  3. Compare the contents to the packing slip.

Now you’re done verifying package contents.

How to Verify Package Contents

Verify the package contents before you begin.

  1. Open the box.
  2. Find the packing slip.
  3. Compare the contents to the packing slip.
  4. Enter your product codes into our database so we can send you product updates.

Now you’re done verifying package contents.

So you can write content one time but add variations to it and then select those options during the publishing step. This is a big cost savings if you translate your content because once you’ve translated the core instructions, you only have to send the variations out to translation. In this case, you’re sending 14 words instead of 46. You can have a big cost savings.

Style Sheets Define the Formatting

XML authoring programs come with standard style sheets, or XSLTs (Extensible Stylesheet Language Transformations), which defines styles for each element in the DITA standard and each output type. You can modify the style sheet to apply your company’s styles such as font types and colors, but it does take some coding skills.

Conclusion

There are a lot of publishing options for XML-authored content such as selecting content from a variety of files and being able to publish to multiple outputs.

Structured writing is a complex topic because it can be applied in so many different ways. In this series of blog posts, I’ve focused on how to apply structured writing in terms of technical content using a XML-based authoring program, but there are many more applications. This is my last blog post in the series on structured writing and I hope you’ve enjoyed the series.