Authoring Documentation with XML

The Benefits of Markup Languages.

Enhance Docs Using Structured XML.

When authoring a technical publication, utilizing a markup language is an easy way to enhance the content. A publication can be as basic as a landing page of a website or thousands of pages of unstructured content. By incorporating a markup language, authors can easily write, update, and edit publications.

Markup language is defined as a standard text-encoding system consisting of a set of symbols. These symbols are  inserted into a text document in order to regulate the structure, formatting, or relationship between its parts. Much like computer code, markup language uses elements such as tags or brackets inserted “around” the words and sentences of a publication. These elements give the publication rules that define it. 

There are 3 primary markup languages:

• SGML (Standard Generalized Markup Language) – The original, developed in the ’80s, SGML breaks down human language so that a computer can interpret and display the data. 
• XML (Extensible Markup Language) – A more efficient version of SGML, it uses beginning and ending tags that can be used to identify data, moving beyond simple display functionalities. 
• HTML (Hypertext Markup Language) – The standard for the internet, it is used for encoding web pages, allowing the browser (computer) to interpret the display of the content.

If this seems complicated, it’s not. Because computers cannot easily understand how humans process language, we use these tools to give computers the ability to categorize, store, and find content. XML goes beyond simply displaying data by allowing us to structure technical content to our liking.

Here’s an Example

Let’s pretend a restaurant creates a new menu for its mobile application. They hire a UX Designer to design the app and a Technical Writer to generate the written content. To structure the content,  the Technical Writer uses XML to categorize the content. Below is an example. Notice the brackets around each item.

<lunch_menu>

    <food>

          <name>Turkey Club</name>

          <price>$10.99</price>

          <Description>Double Decker sandwich piled high with Turkey, Lettuce, Tomato</description>

          <calories> 650</calories>

</food>

</lunch_menu>

By incorporating XML into the authoring, it categorizes each component of the menu. This will help later when the chef needs to update the menu. Using XML, he can do so easily through structured content. 

Now, imagine the chef had created hundreds of menus and needed to update them. Instead of authoring new content for each menu, he can refer to XML to update each category. This save’s the chef time and money. Finally, imagine the chef wants to create a database of every single dish created in the world, then categorize it by region. This is where XML stands out.

Structured Authoring Saves Time
Writing teams use XML because it is easy and interchangeable. Because the data is categorized, teams can efficiently search, edit, and update the document. This makes it unique for writing large-scale publications.

Extensible Markup Language lets the user define elements It can structure the order in which elements occur or how it should be processed and displayed. XML is considered a markup language and a meta language. This means we can incorporate other languages within XML making it versatile.

Styling and XML

Earlier, we talked about how XML goes beyond simply displaying data. If a user needs to incorporate additional languages, they can add languages such as CSS or XSLT to change the visual display of the item. And because the documents stray away from proprietary formats (word, excel) the user can create and share content through different software and platforms. 

Simple XML Rules

To make XML one of the most coveted formats available, developers have created a set of rules that describe a “legal” XML document. Think of these rules as open standards so anyone can use the language.

There are two levels of “legality” in XML:

• Well-formed.
• Valid.

A well-formed document follows the rules:

• Documents must contain a single root element that contains all other elements.
• Elements are properly nested.
• All elements must be closed with a tag (</tag>).
• Attribute values must be quoted. 

In Closing

The possibilities of using XML greatly outweigh conventional formats such as .word. Using XML markup language gives Technical Writers and Documentation Specialists the flexibility they need to create adaptable, interchangeable, and flexible documentation.