What’s the big deal with XML?

XML (eXtensible Markup Language) is one of those initialisms that remains in the background of the tech industry. It pops up in almost every major office software suite (did you ever wonder what the x stands for in .docx?). It shows up all the websites that use XHTML (about 34% of the websites out there) and each RSS feed that you read. And, if you know any technical writers, they probably won’t shut up about DITA (Darwin Information Typing Architecture).

So, what makes XML so special? Well, the answer depends on who you are and how you use XML. Writers like XML because it gives them full control of their text. Developers like XML because they can easily repurpose content. And, designers like it because they can apply stylistic changes on the fly. But, before we explain these benefits in too much detail, we should probably explain what XML is.

What is XML?

XML stands for eXtensible Markup Language. Like HTML, XML is a markup language. Markup is the information that tells a computer how to read content, such as text. For example, this website uses HTML markup (actually, a combination of HTML, CSS, PHP, and Markdown) to tell your web browser where to display text, what font to use, and when to display a word in bold. Without some sort of markup, it would be almost impossible for your computer to properly display content in web browsers, desktop publishing programs, or even applications like games.

Unlike HTML, XML focuses on what the data is rather than how the data looks. That is, the markup in XML tells the computer the content type, and a separate style sheet tells the computer how to display the content. In HTML, the markup only tells the computer how to display the content. So, if you want to change the font in all of the headings on your HTML webpage, you have to change each one individually. In XML, you can simply change the entry that specifies the heading font in the style sheet.

Another notable difference is that XML doesn’t use predefined tags (tags are units of markup). HTML markup is the same everywhere. So, if you use an <h1> tag in HTML, an HTML reader automatically knows that it is a top-level heading. In XML, a style sheet is needed to define the tag, but you can also name the tag anything you want. For example, you could name it <section_heading>, <page_heading>, or even <the_only_heading_you_will_ever_need>. This is what puts the eXtensible in eXtensible Markup Language (XML), and you can create as many tags as you want – which means that you can make your content as nuanced or lightweight as you need.

So, why is XML so great?

Extensibility

XML emerged as a response to the inflexibility and inefficiency of HTML. The standard on which XML is based, SGML (Standard Generalized Markup Language), was deemed too complex, so XML was made to simplify it. XML ditches the unnecessary elements of SGML while still retaining the key principles that the markup needs to describe the content. By abandoning predetermined tags and unnecessary elements and allowing content creators the flexibility to create their own tags, XML offers a lightweight and flexible solution for transporting information, especially text.

Extensibility also makes XML easier to use and maintain than other markup languages. Authors can intuitively name tags based on their functions. Consider the following example.

< ?xml version="1.0" encoding="UTF-8"?> 


  
    Dear Mr. Hughes,
  
  
    I so enjoyed your last film and do hope that you make another.
  

Based on the names used in the tags, you can infer the basic structure of the document and the type of content that each tag contains. Furthermore, you or a new employee could return to this document several years down the road and still figure out what the tags mean.

Strictness

XML is also far stricter than HTML. The rigid syntax required by XML results in smaller, faster, and lighter browsers. For example, XML is stricter than HTML in the following cases:

  • Case sensitivity: HTML is not case sensitive, while XML is.
    A <Paragraph> tag is not the same as a <paragraph> tag.

  • End tags: HTML lets you get away with not closing elements, while XML doesn’t.
    A <p> tag won’t work without the corresponding end tag (</p>).

  • Quotation marks: HTML lets you use value delimiters without quotation marks, while XML doesn’t.
    <object width=100> won’t work, but <object width=”100”> will.

  • Nesting: HTML lets you overlap elements, while XML doesn’t.
    <b><i>Cattle</b></i> won’t work, but <b><i>Cattle</i></b>.

In the past, some Internet browsers devoted up to 50% of their code to correct the mistakes or inconsistencies in HTML content. By imposing a more rigid set of rules, browsers and other programs that process text (often called parsers) no longer need to account for mistakes in the markup. Paying a little more attention when writing is a small price to pay for better overall performance.

In addition to being strict about syntax, XML can also include rules about the structure of your documents. For example, if you were creating an employee database, you could create an <employee> element that must contain <first_name> and <last_name> elements. Doing so ensures that the required information is included and that all unnecessary information, such as an employee number, is excluded.

Easy Data Exchange

Although extensibility and simplicity added to its early success, XML’s greatest claim to fame is that it allows authors to easily publish the same content to different media. Because XML concentrates only on the content type, the content remains independent of the medium. So, authors can write and edit a document in XML and publish it to a website, user’s manual, and helpdesk script. This facet of the XML is often touted as single-source – multi-target. In fact, content reuse has catapulted DITA, an XML standard maintained by OASIS Technical Committee, to the forefront of the technical writing world.

Furthermore, XML relies on free open standards, such as the XML 1.0 Specification, so it avoids the bulk, complexity, and inaccessibility of propriety data formats, such as those used in the older versions of desktop publishing applications like Word. XML content and markup is stored as text that authors can configure directly. Even when using an XML editor, such as FrameMaker, authors can still output the XML text to make changes or transfer the content to another format.

Conclusion

So, back to the question at hand: What makes XML so special? Well, it’s right there in the name: extensibility. Writers and developers are constantly finding new ways to use XML to accomplish their goals in a variety of media formats, and XML supports the freedom they need to do it. That, coupled with its ability to be intuitive and strict in both code and structure and easily distributed to multiple channels means that XML will continue to be a staple of the IT community for years to come.

Tame Wild Writers with a Style Guide

A writer’s room without a style guide is like the wild west: cowboys making their own rules, lawlessness and grammatical errors, and gunfights at the OK corral. Alright, the last one might be a bit of a stretch, but the other points still stand. This article discusses how to bring law and order to your writer’s room through a codified manual of style. This process might not be easy, and you may have a few showdowns at high noon, but in the end you’ll end up with a functional community of writers all working towards the same goal.

Finding Support

The most essential, and perhaps hardest, part of writing a style guide is receiving support from your company. Of course, your company would love a style guide to flash to clients and keep their writers in line, but they’re not likely to schedule time that could be spent doing billable work making a style guide. So, the first step in creating a style guide is convincing your managers of its worth. Thankfully, style guides offer a number of benefits that appeal to budget-conscious managers.

First, style guides save your team time in the long run. Style guides allow writers to concentrate on the content without being distracted by having to look up documentation and grammar conventions. Furthermore, they don’t need to be extensively briefed on matters of style when taking over a project from another writer. Finally, style guides cut down on debates between writers (at least the ones concerning grammar and punctuation), which saves everyone a lot of time and a little bit of tension in the office.

Second, style guides develop a brand that your company can leverage. Many companies, including Latis Global Communications, employ multiple writers at any given time. Often, there’s no guarantee that we can assign all of the projects from as client to a single writer, so the style used for a user’s guide may not match the one used for the accompanying administration manual. In fact, even the titling conventions may differ! A comprehensive style guide, well implemented, ensures that the style and voice of the writing remains consistent throughout all of a company’s projects.

Getting Started

After you’ve convinced your boss that a style guide is a valuable tool, you face another sizable challenge: the writer’s room. Writers – whether technical or not – hold fast to their views, especially with matters of grammar and punctuation. My first time implementing a style guide, I decided no harm could come from a simple open forum among the writers to start things off. Of course, the forum quickly dissolved into a generational battle about issues such as contractions in manuals and ending sentences with prepositions, so this was not the smartest option.

Instead, you should appoint someone to act as a style sheriff. The style sheriff is responsible for writing and maintaining the style guide as well as settling disputes regarding style issues. The style sheriff should have an eye for details and a genuine interest in matters of style. Look for the writer with the most well-worn copy of Struck and White. It also helps if the sheriff is appointed by someone in charge, such as a division head or team manager, in order to avoid some of the disputes that are bound to arise with one writer dictating matters of style to the others.

As their first action, the style sheriff should choose a base style guide to inform their decisions. The most popular style guides for the IT market are the IBM Style Guide: Conventions for Writers and Editors and the Microsoft Manual of Style for Technical Publications. The former advocates a tone similar to that used in academic writing, while the latter promotes a more conversational tone. Either style guide is acceptable. However, these style guides should only inform stylistic decisions. The lengths of these style guides (389 pages and 464 pages, respectively) make them difficult to memorize for new writers. 20-30 pages is a better length for an internal style guide because new writers can easily digest it in a night and master it in a week.

Depending on your industry, you may want to consider authoring a glossary in conjunction with the style guide. The Microsoft Manual of Style for Technical Publications contains a substantial glossary of user-facing technical terms. However, you may want to use a more technical glossary, such as the IEEE Standard Glossary of Software Engineering Terminology, or even a controlled language glossary, such as glossary found in the Aerospace and Defense Simplified Technical English standard. Whichever you choose, you should treat the glossary in much the same manner as the base style guide. That is, you should incorporate entries from the base glossary into an internal glossary that contains only those entries relevant to your company in order to enhance the usability of the glossary. Tips on how to create a glossary will be covered in a future blog entry.

Lists and Meetings

After selecting a base style guide, you can start considering what to include in your internal style guide. Include too many topics, and users won’t be able to effectively memorize the style guide. Include too few topics, and users won’t be able to find the answers they need.

A good strategy when first developing your style guide is to list all of the topics covered in the base style guide. Then, armed with this list, review three or four recent projects and check off any style topics that match aspects of the project. For example, if the projects contain tables, then, naturally, you should check off the topics related to tables in your list. Finally, create a new list that includes only the checked off topics.

Distribute this list among the writers at your company, and then organize a meeting at which the writers can propose new topics. You should also allow the writers to vote on grammar and style issues that may be particularly contentious, such as ending sentences with prepositions and the use of Oxford commas. At the conclusion of the meeting (or series of meetings) you should know the topics that your style guide will contain as well as your company’s stance on most style issues.

Writing the Style Guide

After determining what your style guide will cover, you can finally start the fun part: Making decisions about grammar and punctuation. If that doesn’t sound like fun, then you may want to step down as style sheriff or risk a showdown when you can’t justify not using the Oxford comma.

Each entry in an internal style guide should state a specific rule, outline some of the exceptions to that rule, and then provide an example highlighting the rule. As in the following:

Compound Nouns

Avoid using more than three nouns when creating compound nouns. Use prepositions to clarify noun clusters.

Examples

(O) Maintenance procedure for the operator area

(X) Operator area maintenance procedure

The style guide should abide by the same formatting and style that it recommends. This allows writers to infer answers to style questions while reading, which saves time when looking up multiple issues. Furthermore, your style guide should be just as readable as any other document that you produce. So, it needs an appropriate amount of white space, pages that readers can scan easily, and an intuitive structure. Finally, formatting your style guide in this way ensures that all of your company’s internal documents, such as standard operating procedures and employee handbooks, have a consistent style and appearance.

In addition, you should author your style guide using the software most often used by your company. For example, if your company uses Microsoft Word, then you shouldn’t author your style guide in Pages. Furthermore, you shouldn’t author your style guide using a tool or markup language that is unfamiliar to members of your team. For example, if your team regularly authors documents in XML, then it wouldn’t make sense to author your style guide in Markup.

Distributing the Style Guide

After writing the style guide, determine whether your writing team would benefit most from a physical copy of the style guide, an electronic copy of the style guide, or both. If publishing the style guide electronically, select a format that uses a program openly available to your writers, such as PDF. If publishing hard copies of the style guide, consider distributing the guides in small binders so that the information can be easily updated without incurring too many additional costs.

You should then distribute the style guide in conjunction with a kickoff meeting involving all of the writers and other personnel that will use the style guide. This meeting should instruct the personnel how to effectively apply the style guide to their writing and the scope to which it applies. For example, you should specify whether the style guide applies to all documents and written correspondences or only those that the customer will see. You should also specify who will update the style guide and how personnel will be notified of such updates.

Conclusion

A good style guide can help you bring law and order to an unruly community of writers. However, implementing a style guide requires tenacity, strength, and the support of your company. It also helps if you’re organized and have a plan of action. I’ve armed you with the plan, so it’s time for you to strap on that sheriff’s badge and set the town straight.