Structured Writing Part 3: Tools

February 9, 2017 Daniela Bustamante

Structured writing is not necessarily dependent on a tool, other than a writing program, if you have a simple scenario like creating a letter in Microsoft Word. However, structured writing is often used in more complex scenarios, such as if you have hundreds of topics authored in an XML-based editor, like XMetaL. Since there are a wide range of scenarios, I’m going to focus on structured writing as it applies to reused technical content authored in XML using DITA, which does require tools. In this scenario, I’ll talk at a high level about the five main tools that are required.

1. XML Authoring Tool

You need an XML authoring and editing tool such as oXygen XML EditorXMetaL or Arbortext Editor. These tools come with a range of capabilities and licensing structures.

2. Writing Architecture     

DITA (Darwin Information Typing Architecture) is an open architecture for structured content. It allows you to label all the components of your content with predefined elements. While there are many different elements overall, the main elements for topics are taskconcept and reference. For example, the topic of “How to Verify Package Contents,” which I used in my previous blog post on structured writing, is a task element. To use DITA, you first need to audit your content and then see how it fits into the standard. You can also have variations for cases where content doesn’t fit into the architecture. While there are other content models, DITA is the most commonly-used standard for technical writing and XML authoring tools come with DITA support.

3. DTD                           

A DTD (Document Type Definition) is a set of markup declarations that defines what structure is valid. For example, let’s say that we decide for tasks that:

  1. Every instruction needs a header.

  2. Steps must be in a numbered format.

If we write the task like the example below, with the instructions in a paragraph form, the DTD will recognize that the format isn’t correct and you’ll get an error:

               How to Verify Package Contents

              Open the box and find the packing slip. Make sure the contents match up.

The DTD validates the structure as you develop content so you won’t be able to do anything that doesn’t fit into the structure. Standard XML authoring tools come with a DTD. You can also create your own or modify existing ones, which you may want to do if you have specializations.

4. Style Sheet (XSLT)

A style sheet, or XSLT (Extensible Style sheet Language Transformations), defines the formatting for each element and output type. Standard XML authoring tools come with style sheets but you may want to modify them to include your company’s style standards. For example, if you want to change the font of numbered steps to Calibri 11 point, you’d define it in the style sheet.

5. Component Content Management System

Unlike standalone documents, a document created in XML may contain tens or hundreds of smaller XML files, which are pulled together by creating a DITA map. All of these little XML files need to be stored and managed in a Component Content Management System (CCMS). Each file can be reused across many different documents and outputs. A CCMS manages the lifecycle of each of these files. There are many CCMS options with different features and costs.

Conclusion

The five main tools used in structured XML writing are an XML writing tool, a writing architecture such as DITA, a DTD, a style sheet and a content management tool. In the next blog posts in this series, I’ll get into more details about creating content for reuse using DITA.

Further Resources on Translation Services

You may gain further insight into content strategy, content localization, translations and related topics by reviewing the previous blogs written by GPI: 

 GPI's content strategists and localization specialists can help analyze your website and provide guidance on any localization and global digital marketing requirements. GPI also offers Global Search Engine Marketing Services and many other Translation Services.

About the Author

Daniela Bustamante

Daniela has over 16 years experience in the translation, localization and language instruction professions. She holds a degree in Sworn, Literary, Technical, and Scientific Translation from the Instituto Nacional de Enseñanza Superior Olga Cossettini in Rosario, Argentina. Starting her career as a translator for English-Spanish/Spanish-English in 1990 over the years she has worked for several Localization Agencies as a translator, assistant project manager and senior project manager. She has completed a wide range of professional certifications in document and website localization with emphasis on translation, budgeting, quality control and project management including The Localization Institute’s Triple Certification in Localization Project Management (Localization Institute Chico, CA, USA).

More Content by Daniela Bustamante
Previous Article
News: Magento Acquires BlueFoot CMS Technology
News: Magento Acquires BlueFoot CMS Technology

At the end of 2016, Magento announced they have acquired the technology behind the BlueFoot CMS and page bu...

Next Article
MODX and the GPI Translation Services Connector
MODX and the GPI Translation Services Connector

GPI’s Translation Services Connector for MODX is a plugin that enables users of the MODX content management...

Ready to translate your documents, software or website?

Request a Quote!