One of the most important characteristics of effective technical writing is consistency; be it in form, function,

or style of writing. Structured authoring helps maintain consistency in the structure of content.
For example, an organization might define a chapter and sections within the chapter as:

Sample
Structure for a Chapter

Structured
Authoring Example: Sample Structure for a Section

THE TRADITIONAL WAY

Most organizations define a content structure and propagate it through training, mentoring, and style guides. It
is with practice that technical writers master the intricacies of the defined content structure. Until then looking
up the style guide or talking to the more experienced members of the team is the only option. Even after that, it
is only the very disciplined of technical writers who is able to stay faithful to the defined structure.
Deviations from the defined structure are typically detected in a review. So one of the reviewer’s focus areas is
ensuring that the defined content structure has been maintained. Given that a reviewer typically handles
multiple technical writers, a significant amount of time of the reviewer’s time is spent on activities like
checking document structure.

STRUCTURED AUTHORING: USING TECHNOLOGY TO

DEFINE AND ENFORCE CONTENT STRUCTURE
The reviewer should ideally been concentrating on the content; relevance, completeness, flow, readability, and
more. Anything that takes away time from the focus on content reduces the effectiveness of the reviewer.

Structured authoring is especially useful for organizations with large and/or

geographically dispersed technical communications teams.
Structured authoring uses technology to define and enforce content structure. It aids the technical writer in
adhering to the structure by specifying the “allowable” type of content at a particular place in the document.
Even if the technical writer moves away from the defined structure, the structured authoring system will warn
the technical writer of the misdemeanor. (You cannot use a table here!) So the technical writer no longer needs
to remember the prescribed structure and the associated dos and dont’s. The structured authoring system does
that!
From the reviewer’s point of view, structured authoring systems free them from having to check for validity of
a document’s structure. That is more time that the reviewer can dedicate to the content.
Another benefit is that structured documentation systems often allow presentation (formatting) to be associated
with content based on its position in the document structure. For example, a title in a first level section may use
the style Heading 1, while a title within a sub-section may use the style Heading 2.
So the technical writer does not have to remember the formats to be applied. It is also one more thing off the
table for a reviewer.
All in all structured authoring aids in improving the efficiency of the technical writing team and helps them in
improving effectiveness.
In an earlier post, we had introduced the concept of structured authoring. From that post, we realise that there
are two imperatives for structured authoring:

1. defining a content structure

2. enforcing the defined structure

In this post, we will look at the first and the most important part of implementing structured authoring
systems, defining the content structure.
Assuming we are creating a content structure for a particular document, we have to analyze:

1. the structure of the document

2. the type of content in each section
3. the relationship between various types of content

 In the following sections, a * against an information unit indicates that it is

optional, but can be used more than once.
 A + against an information unit it must be used at least once.
 If there is no symbol against an information unit, it is mandatory and can be used
only once.

Consider an email. We could define its overall structure as:

Thus, an email starts with the Address section. The next section in an email is the Subject, and this is
followed by the Body. All three sections are mandatory and must appear in the specified order.
Let us take a closer look at the Address section. It could be defined as:

Thus, the Address section must have a To section while the CC and BCC sections are optional. However, if
both CCand BCC are used then CC must precede BCC.
Next we take define the TO, CC, and BCC elements as containing one or more email addresses:

Finally, we define Body as starting with a mandatory Salutation (we are sticklers for etiquette! :-)) followed
by the Message which must have at least one Para. This Para can be followed by one or
more Para, List, and/or Imageelements in any order. Finally, there is the mandatory Signature section.
We define the Para as containing Text with the option of having Hyperlink, Bold and/or Italic elements.
Just as we defined a Para, we can define List and its constituents as:

Thus, you can see that defining the content structure has to be an extremely meticulous exercise resulting in a
detailed content definition. This is typically the job of an information architect.
The previous post, Structured Authoring: Defining the Content Structure, described the first step in
adopting structured authoring; analyzing and defining the content structure.
However, as of now, the content structure is on paper. The next step is to use technology
to encode and enforcethe defined content structure.
So what kind of technology would we need?
When choosing a technology for structured authoring, your primary requirement is that the chosen technology
should allow you to define the content structure.
So, you should be able to:

 identify the start and end of each piece of content. For example, the start and end of the body of an
email.

 describe/label each piece of content using terms relevant to you. For example, give the body of the
email a name such as Message.

 specify relationships that exist between pieces of content. For example, every mail starts with
an Address. Each Address must contain a To, CC, or BCC section. It can also contain any or all of
these sections. But when more than one of the sections are present, they must be in the specified
order. That is, if a mail has To and BCC, then To must come before BCC.You get the picture, so we

won’t bore you further!

 specify which pieces of content are mandatory and which are optional.

These are just some of the most requirements and one technology that meets all these is
eXtensible Markup Language, known popularly by its acronym XML.
A First Look at XML
XML is a markup language that helps you to define and use tags to describe content.

XML and Structured Authoring: A Sample XML File

XML is best explained using an example. Consider an email that could be represented as:

 Content enclosed in <> is called a tag.

 Tags are used to identify and describe the content.
 Tags are always used in pairs and enclose relevant content within them. <tag_name> is called a start
tag, while </tag_name> is called a end tag.
 Tag names are something you decide to suit the content you are describing. For example, we have
used <message> to describe the email body.
 You can have tags within tags to create a hierarchy for the content and establish a relationship
between various pieces of content. For example, you have an outer tag <email> which contains the
 tags <address>, <subject>, and <message>. This can be interpreted as an email contains an address,
subject, and message.

This is a very basic explanation of XML. As you can see from the example, the XML document describes and
structures the content in a human-readable form.
In an earlier post, Structured Authoring: Introducing XML, we saw the role XML had to play in structured
documentation. Now let us take a look at how the implementation works.
In the post titled Structured Authoring: Defining the Content Structure, we discussed how to go about
analysing the content and breaking it up into smaller units. While the content analysis and definition is a pen-
and-paper exercise, the content structure has to be defined using technology so that it can be enforced.
This is where the Document Type Definition (DTD) or Schema comes in.

For the purpose of this preliminary discussion, we are going to use DTD and Schema as
analogous terms.
What does a Document Type Definition (DTD) do?
A document type definition, or a DTD as it is commonly called, defines the structure of a document. It
specifies the document structure in terms of the tags that may can be used in a document, where and when
these tags can be used, and the attributes that each of the tags may have.
Every unique document will have its own DTD or Schema. For example, there will be separate DTDs for user
manuals, release notes, case studies, and API references.
When an author wishes to create a particular type of document, the author has to base the document on the
relevant DTD.

The DTD itself is an XML document and must adhere to all rules of XML.
Validating an XML Document Against the DTD
When a DTD is associated with an XML document, the XML document is compared against the DTD to
ensure it is structured as specified by the DTD. This process of comparison is called validation and it is
performed by the validating parser.
When the XML document adheres to the structure defined in the DTD, it is said to be valid.
What Happens If an XML Document is Invalid?
When you are in the authoring stage, the XML editor typically warns you that the document is invalid, but you
can save the document. However, when you generate the output or process the document in any way, the
invalid document will not be processed. This means that, typically, this document is omitted from the output.
So, the DTD is the foundation on which the structured authoring system is built.
In the four posts in this series that explains Structured Authoring looked at:

1. Understanding Structured Authoring

2. Structured Authoring: Introducing XML
3. Structured Authoring: Defining the Content Structure
4. Structured Authoring: The Role of the DTD/Schema

In this post, we look at a Document Type Definition (DTD), which is the formal definition of a content
structure.
Consider the following image which shows a sample DTD for an email.

This DTD specifies that:

 an email must have three elements; address, subject, and body.

o address must contain one sender and one receiver element.
 the sender must contain one emailaddress.
 the receiver must contain a to element, and an optional cc and/or bcc element.
 the to, cc, and bcc elements must contain one or more emailaddress elements.
 the emailaddress element contains text.
o the subject element contains text.
o the body element must contain a salutation, message, and signature.
 the salutation element contains text.
 the message element must start with a para element.
 After the initial para element, there can be number of para, list,
or image elements and in any order.
 the para element contains text.
  the list element must contain one or more listitem elements.
 the list element has an attribute type which can be given the
value bullet or number, with bullet being the default value.
 the listitem element contains text.
 the element image is an empty element with a mandatory
attribute href which contains text.
o the signature element contains one or more para elements.