Nolwenn Kerzreho, IXIASOFT
March 15, 2020

Some writers and specialists claim it’s too difficult to write in DITA and that the learning curve is too steep. Some other specialists and documentation managers claim that they can start new hires writing in DITA in a couple of hours. This article is the first part of a series of posts about writing practices that authors must adapt, adopt, or shed.

There is a lot of confusion about how difficult writing in DITA can be and this article’s goal is to clarify the challenges for information developers and technical writers alike. This article is based on my experience teaching DITA authoring to two main audiences:

  • To content development and SMEs groups in various industries, from 2007.
  • To technical communication students in several universities in France, from 2008.

Of course, the learning path depends on each individual’s experience, grasps of concepts, and know-how. However, three main aspects emerge that everyone can relate too, depending on their experience.

  • Reinforcing best practices –  sometimes unconscious practices and knowledge the authors are already familiar with.
  • Adopting new practices – new practices linked to enlarged responsibilities and capacities of modular, structured content, and the DITA standard.
  • Letting go of old practices – it may be counter-intuitive but letting go of specifics from old tools and other proprietary formats is sometimes the most challenging part for some authors.

Teachers and trainers can use those as a basis for assessing the learning requirements for each group. This article will talk about the first of these aspects: Reinforcing Best Practices.

Getting Started

Most writers will be familiar with structures and templates, styling, categories and document identification, and crafting abstracts or briefs. DITA, as an open international standard, does take these aspects to a new level and constrain the writers to a certain level. The key is to understanding topic-based authoring (or modular documentation) will require the technical authors to:

  • Make a clear choice into what type of topic1 must be written.
  • Use tags instead of styles to clarify the meaning of text segments.
  • Enrich the content with metadata that makes sense to identify not only the full output, but each content piece.

Understanding topics

Topic-based writing should be easy to grasp for authors who are familiar with:

  • Transversal ISO-IEC-IEEE 82079-1 2019 Preparation of information for use (instructions for use) of products — Part 1: Principles and general requirements standard, which separates content into instructions, conceptual information, and reference information.
  • Simplified Technical English – which separates instructions and conceptual information.
  • Information mapping, which separates content into instructions, processes, descriptions…
  • Web patterns and organizations’ templates (iFixIt, HowTo…) that provide structure for instructional information.

Once the topic type is established, the writer follows the expected information derived from the type. This structure is based mostly on common sense and best practices from the technical communication field.

Using tags instead of style to add meaning to text fragments

XML, as HTML, is a tag language. This means the text can be enriched with value-add information. Most authors will not write these additional tags manually. Topic templates and easy-to-use interfaces provide clickable actions for the authors to select and apply the right tags.

Most writers using a style guide such as the Microsoft writing style guide or editorial style guides use styling to enrich the value of the content or convey the objective of a content. A quote would be in italic whereas, in DITA, the writers will select the <cite> (or <longquoteref>) element.

Within the architecture itself for instructional topics, for example, to convey ordered steps in a task, the phrase Step 1. Create a new task topic, could be written in XML (or HTML) within a paragraph (p) element:

<p>Step 1. Create a new task topic.</p>

This is interpreted as a paragraph, but there are no other elements to state this is an instruction. The author has to add numbers to follow the flow and will need to adjust each time the test ‘Create a new task topic’ is used in another context or series of steps. DITA, on the other end, will take the semantics further by adding more details, such as:

<steps><step><cmd>Create a new task topic.</cmd><step><steps>

This is interpreted that the text is a command within a step, included in a series of steps in an instructional topic. Because the style sheet is separated from the content, the numbers and keyword (step) are added automatically by the XML editor and inserted at publishing.

Within DITA, signal words for safety information, notes, legends, will be added automatically and numbered by the XML editors and the publishing process.

Categorizing and labelling for product and information identification

Whatever their industries, every writer relies on documentation identification and product identification. These are two important parts of labelling content. When switching to DITA, that information should be inserted at the topic or at the collection level. In most cases, the task of choosing which identifiers are required and how they should be transferred in DITA will be taken by an information architect or a senior DITA expert.

This is really a matter of mapping the current identification requirements and enriching the topics with all required identification when they are used for different products.

“Labels and catalogue information are part of a topic’s or collection’s metadata. Metadata allows content to be filtered, sorted, processed, and otherwise manipulated. Choosing accurate labels will result in more flexible documents.2”

The end result is to provide machines and processors ways to properly identify content and apply search optimization, facets and manage product identification.

Abstracts and briefs to match web-writing best practices and provide quick recognition to end-users

Most writers with experience in web writing or journalism will know about the inverted-pyramid method. The method not only makes content more accessible; it also helps with search engine optimization and complies with web accessibility guidelines.

The inverted pyramid refers to a story structure where the most important information (or what might even be considered the conclusion) is presented first. In this case, the first paragraph, often found right after the title, helps advanced users understand the key points, and all users make a choice whether this particular topic will provide them with the answer they are looking for.

Short descriptions are hard to craft. They should be short, focused on the main points in the topic itself, they are not an expanded view of the title, nor glue text.

Example of a bad short description for a topic called Eco Printing:

The explanation below is on the eco-printing procedures for the eco printing.

Example of a better short description for a topic called Eco Printing:

The Eco function cuts toner consumption and paper usage. The Eco function allows you to save print resources and lead you to eco-friendly printing. If you press the Eco button from the control panel, eco mode is enabled. The default setting of Eco mode is Multiple pages per side (2) and Toner Save.

Example of a good short description for a topic called Eco Printing:

Use the Eco function to save paper and toner. Press the Eco button from the control panel to enable the eco mode. The default settings are Multiple pages per side (2) and Toner Save.

——————————————————————————————————————————-

Future articles will discuss the next two aspects of learning DITA: Adopting New Practices and Letting go of Old Practices.

Sources:

Amy Schade, Inverted Pyramid: Writing for Comprehension (online), Norman Nielsen Group: https://www.nngroup.com/articles/inverted-pyramid/

Keith Schengili-Roberts, IXIASOFT and Joe Storbeck, JANAS, Short Descriptions Shouldn’t Be a Tall Order: Writing Effective Short Descriptions (online), CIDM:
http://www.infomanagementcenter.com/product/short-descriptions-shouldnt-be-a-tall-order-writing-effective-short-descriptions/

Tony Self Dr., DITA Style Guide, Best Practices for Authors (online), Scriptorium Publishing:
https://www.amazon.com/Dita-Style-Guide-Practices-Authors/dp/0982811810

Microsoft writing style guide (online), Microsoft:
https://docs.microsoft.com/en-us/style-guide/welcome/

Nolwenn Kerzreho, Training technical communication students in structured content using DITA, in Current Practices and Trends in Technical and Professional Communication, ISTC.
https://www.amazon.com/Current-Practices-Technical-Professional-Communication/dp/0950645990/

1 A topic is a small, self-sufficient piece of information, with a clear objective and a set structure.

2 Dr. Tony Self in The DITA Style Guide, Best Practices for Authors.