Skip to content

Term of the Week: XML Document Editing Standards

What is it?

Vocabularies and processes used to create specialized, editable structures for documents that conform to the XML standard.

Why is it important?

Successful interchange of structured information depends on a common understanding of the vocabularies involved and how they are processed. The standards for providing this take the form of an XML schema and provide common ways of structuring different types of content to facilitate reuse, catalog maintenance, version control, and other aspects of technical documents.

Why does a technical communicator need to know this?

There are many ways to store and process structured information. Within the realm of prose communications, as distinct from data-interchange APIs, XML is one of the most common and successful ways to do so. Most publishing workflows rely on XML at some point by, for example, reading the underlying XML structures of Microsoft Word .docx files as part of a conversion process, generating XML markup for an automated publishing system, or publishing eBooks.

XML document editing standards identify common vocabularies and best practices for reducing costs and increasing reliability. Technical communicators are most likely to encounter one of these XML editing standards:

  • DITA (Darwin Information Typing Architecture): originally developed by IBM, DITA is now maintained as an open standard by OASIS. DITA is based on a topic model, but it is useful for most types of technical documentation. DITA is notable for specialization, a capability that allows developers to extend the vocabulary while remaining compliant with the DITA standard.
  • DocBook: the most mature standard on this list, DocBook was originally designed and implemented by HaL Computer Systems and O’Reilly & Associates around 1991. Today, it is maintained by OASIS. Although originally designed around a book model, it has evolved to be useful for help systems, ebooks, and other forms of technical documentation. DocBook is widely used in the open source world.
  • oManual: started when O’Reilly Media and the iFixit online repair website wanted a data format for exchanging their procedural manuals. It is a standard for semantic, multimedia-rich procedural manuals and also an API designed to provide quick access from shared locations (e.g. cloud) on mobile and other devices. It is an open standard, maintained by oManual.org, and has been approved as an IEEE standard.
  • S1000D: originally developed by the AeroSpace and Defense Industries Association of Europe (ASD) for use with military aircraft. It is now also used in many other parts-intensive contexts. It is maintained by the S1000D Steering Committee, which is made up of aerospace and defense representatives from around the world.

Understanding and applying XML document editing standards reduces the risk of misunderstanding, leverages existing tools and technologies, reduces costs, and increases productivity.

About Norman Walsh

Photo of Norman Walsh

Norman Walsh is a Lead Engineer at MarkLogic Corporation where he helps to develop APIs and tools for the world’s leading enterprise NoSQL database. He has also been an active participant in a number of standards efforts worldwide: he was chair of the XML Processing Model Working Group at the W3C where he also co-chaired the XML Core Working Group. At OASIS, he was for many years chair of the DocBook Technical Committee.

With two decades of industry experience, Norm is well known for his work on XML, XSLT, DocBook, and a wide range of open source projects. He is the author of DocBook 5: The Definitive Guide (O’Reilly Media, 2010).

Term: XML Document Editing Standards

Email: ndw@nwalsh.com

Website: nwalsh.com/

Twitter: @ndw

LinkedIn: linkedin.com/in/normanwalsh