The Future of Documentation Belongs to XML, Extended Markup Language

Introduction

XML, that is, Extended Markup Language, is the future of technical writing.

Two Reasons

There are TWO important reasons why that is so.

REASON 1: XML is at the heart of “single sourcing” movement. The whole idea is to write something once and then “tag” it in such a way that it would be possible to publish it in many formats and on many gadgets and platforms without making any further changes to it. XML makes that possible.

One bottleneck at this time of writing is this – it is still very hard to format XML-tagged text in exactly the way you want it. XML is not a designer’s dream, by any means. Attaching a “style sheet” to an XML text and converting into a pleasant and looking well laid out document is still not easy. But better minds are working on it day and night and I’m sure sometime in the future we’ll get over this hump as well.

REASON 2: XML is a documentation manager’s dream since writing once and publishing many times drops unit production costs tremendously.

Imagine hiring a team to publish a magazine, another to post to a web site, and yet a third team to compile a help file by using the SAME content! Compare that to a single team that publishes the same content in three separate ways, all thanks to XML? The choice is obvious.

The easiest way to generate an XML document is to use Adobe FrameMaker in its “structured” mode.
Open XML Main Components (Public domain illustration courtesy of Wikipedia Commons)

Here is a general 12 Step Study Outline for the quickest way to learn FrameMaker-based XML authoring, based on my over ten years of Fortune 500 experience.

12 Steps

1) Begin with the basic facts about XML (Extended Markup Language). Learn the difference between “well-formed” and “valid” XML.

2) Find out how to switch your FrameMaker to “Structured” mode.

3) Next, learn what a DTD (Document Type Definition) is. Learn the difference between DTD and Adobe’s proprietary EDD (Element Definition Document) files.

4) Learn how to export an EDD from an already structured FM document.

5) Learn how read and understand an EDD file. Learn how elements are defined and formatted inside the EDD. Learn how to use a Formatting Template with an EDD.

6) Prepare your document template so that you know exactly what the main components of your document are. Do you have an Introduction follow the Title? Is the Header1 followed by body text or Sub-header1? Will a “Note” look the same regardless of whether it’s a part of the Body or a Table Cell? Once you have that written down, start learning how to write an EDD from scratch.

7) Learn how what Read/Write Rules is all about and how it’s used with an EDD.

8] Learn how to assign attributes to individual elements.

9) Learn how to derive a DTD from an EDD.

10) Learn how to import an EDD.

11) Learn how to generate and modify a Conversion Table to convert an unstructured FM file into a structured one.

12) Learn what an XLS (Extensible Style Sheet) is; why it is needed; and how it is used to format your XML file.
Learning structured FrameMaker is not easy but it’ll be worth the effort if you are to survive and prosper in the new competitive world of technical communications.

Conclusion

May you single-source and export your joy and enthusiasm for life to every platform that’s available to you!