Professional Documents
Culture Documents
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 Section 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 reviewers 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 reviewers time is spent on activities like checking document 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.
NOTE: 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 donts. The structured authoring system does that! From the reviewers point of view, structured authoring systems free them from having to check for validity of a documents structure. That is more time that the reviewer can dedicate to the content. Another benefit is that structured authoring 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 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. 2. 3. the structure of the document the type of content in each section the relationship between various types of content
NOTE: In the following sections, a * against an information unit indicates that it is optional, but can be used more than once. A
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 BCCsections are optional. However, if both CC and 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. Having analyzed the content and defined a content structure, the next step is to encode the content structure using technology. Stay tuned!
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 beforeBCC.You get the picture, so we wont 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 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.
NOTE: For the purpose of this preliminary discussion, we are going to use DTD and Schema as analogous terms.
What does a 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.
NOTE: The DTD itself is an XML document and must adhere to all rules of XML.
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.
Validation
If an document complies with a given XML Schema, then the document is said to be valid for this schema. A document might be valid for one schema but invalid for another schema. The process of testing an XML document for compliance with an XML Schema is called validation. When an XML document is parsed by an XML parser, validation can be enabled as an optional part of the parsing process. Full validation of an XML document always requires XML parsing. For many documents and schemas, validation typically incurs only a small delta cost (in terms of CPU usage) on top of the cost of XML parsing.
The XML Schema Primer: http://www.w3.org/TR/xmlschema-0/ A tutorial: http://www.w3schools.com/schema/default.asp Best practices for XML Schema design: http://www.xfront.com/BestPracticesHomepage.html