Structured authoring is an important concept in technical writing. It refers to a practice of writing within the constraints of pre-defined rules and structures using XML. Let’s take a detailed look.

What is structured authoring?

Structured authoring is completely different from regular writing, i.e. narrative writing. In regular writing, we take a blank page and start putting our thoughts and ideas onto it. However, in a structured authoring environment, writing resembles “filling a form” (Semantic, Structured Authoring). You take a document with empty fields and fill in information to produce the final outcome. The information that you enter is validated by an XML schema. A document will throw an error or won’t be saved if it is missing required information or if information does not conform to rules.  

What is XML?

XML stands for eXtensible Markup Language. As the Oxford dictionary defines, XML is a computing language that “allows users to define their own customized markup languages, especially in order to display documents on the internet.” 

You probably have heard of HTML – HyperText Markup Language. XML is a cousin of HTML. It is similar to HTML in the sense that it uses tags to “markup” the text. However, XML is different from HTML in several ways as described below:

XML is designed to carry data, whereas HTML is designed to display data

XML code by itself is “just information wrapped in tags” (W3 Schools). It doesn’t affect how text appears on a web page or on a paper. It stores information, which then can be parsed using specialized software to produce different outputs in different formats. 

For parsing HTML, on the other hand, you need a web browser. The web browser reads HTML tags and modifies the look of the content between tags accordingly. 

XML doesn’t have pre-defined tags like HTML

This is one of the reasons why you need a specialized software to parse XML. But the ability to create your own tags is what makes XML so powerful. You can define XML tags to cater to the needs of your organization or industry, which makes exchanging data so much easier.     

How XML is used in structured authoring

XML tags enforce the rules to ensure that content is complete and conforms to the defined standards. You can use XML to set your own rules. For example:

• A definition cannot exceed 100 words.
• Steps cannot include an image.
• A task cannot include more than 10 steps. 
• Front page must include a legal disclaimer.

These rules are saved in an XML schema called DTD (Document Type Definition). Each document is checked against DTD for its validity. For example, if a definition exceeds the 100-word limit, the file will not be allowed to save.

Why structured authoring is used

Many organizations use structured authoring for their technical documentation, mainly for the following reasons:

• Enforcing style guide and content requirements: XML schema ensures that all required content is included in a document and it conforms to legal, stylistic, or other requirements. 
• Consistency in writing: Organizations have many technical writers working on technical documentation. Each writer has their own style of writing, which can make the final documentation feel inconsistent. Structured authoring reduces this inconsistency to create documentation that looks and feels uniform.
• Less time spent on editing: Since many style-guide rules and other requirements can be enforced through an XML schema, the final draft doesn’t need as much editing as an unstructured draft might. This saves a significant amount of time writers have to spend on editing.
• Faster content creation: Writers already have the structure ready, all they have to do is to fill in information under given headings and sections. This reduces the time spent on figuring out what needs to be included in the document and in what manner.
• Cost-effective: All the above points as well as its characteristic reuse and single-sourcing together lead to significant savings for an organization in terms of time and money. 

Characteristics of structured authoring

Structured authoring has following characteristics that sets it apart from conventional writing:

Chunking

Writers create content in pieces – each file contains a chunk of information that can be used in multiple ways. For example, consider a procedural article that includes four parts – 1. Concept explanation, 2. Steps, 3. Known issues, and 4. More information. The writer creates four pieces of content, each containing one part of the article. This way of content creation serves a bigger purpose in structured authoring – single-sourcing.

Single-sourcing or content reuse

Simply put, single-sourcing means creating a chunk of information and using it in multiple places, products, or formats. In our example, the Concept chunk can be used in the procedural article as well as in a glossary document. Similarly, the Known Issues piece can be shared by multiple procedures related to the same product.

This sounds like copy-pasting, but single-sourcing is a completely different and more powerful concept. In single-sourcing, there’s only one file (source) and it is mapped into multiple bigger files. This eliminates the need for copy-pasting. More importantly, this eliminates the need of updating each and every occurrence of the same information whenever you need to update it. You only have to modify the source file and the change will appear everywhere the file is mapped. 

Information architecture or content-mapping

Since content is created in pieces, arranging them into a meaningful way is crucial to achieve the desirable outcome. Information architecture is how the content files are mapped into one another as well as into different forms and formats. Content maps are used to arrange files in a desirable order to create a seamless documentation. The same files can be arranged in different ways in multiple maps simultaneously to create multiple outputs. For example, a combination of conceptual, procedural, and referential documents can be mapped to create an installation manual. These same conceptual files can also be used in another map to create a glossary document. 

Metadata

Metadata refers to attributes added to content. Metadata is information about the content that lives behind the scene. It provides information about the content. Readers don’t need to know this information but those who write or manage the content can benefit from it. For example, each document may have an ID to track content inventory. It can also include the author’s name, the date the document was created, and last updated, and the product it refers to.    

Focus on content

When creating content in a structured authoring environment, writers only need to focus on it’s form and structure. They don’t have to worry about how it would look on a website or in a book. Because, as mentioned before, XML is about “carrying” information. The aesthetics are taken care of by HTML and CSS.    

Structured authoring aims at improving efficiency of the documentation process. It automates several tasks using XML, such as rule-enforcing. It brings consistency across documentation using pre-defined structures. It reduces duplicate content by allowing content reuse. It helps writers focus solely on writing by taking away the design and presentation part.