My DITA experience in 2010 and 2014
When I first encountered DITA (Darwin Information Typing Architecture) at the beginning of my technical communication career in 2010, I had no idea what I was learning about. At that time, the whole field of technical communication was new to me. Because of that, I looked at DITA the same way as I looked at any other new concept; I must study it as much as I can.
Almost four years later, when I discussed DITA at this year’s Congility conference with fellow delegates from other organisations, several people mentioned the same thing: “DITA is difficult, and traditional technical communicators – those who are writers rather than programmers or engineers – do not want to get into coding things.”
I found these remarks quite surprising, because up until that point I thought that most technical communicators are okay with a bit of coding, and they would be happy to learn more about it, if it was required for their jobs.
To prove that it is not difficult to learn DITA, I collected some of my personal findings to show how learning and adopting DITA has become so much easier in the recent years and what the main hurdles are that one must look out for.
I will discuss three topics in this article:
- The rise of easy-to-use XML editors
- The simplified topic-based approach
- The challenges of working with DITA.
1. The rise of easy-to-use XML editors
The first thing to point out, which was also mentioned by Maxwell Hoffmann in the Summer 2014 issue of Communicator, is that XML editors have improved so much in the last couple of years that you can literally use them as traditional word processors, eliminating the need to learn a complex tool.
Both oXygen XML Author and FrameMaker XML Author 12 provide you with a very convenient layout, where you can see your text with tags, but you can also switch to normal and text views (see Figure 1). You can create lists, tables or other commonly used structures from the main user interface.
You don’t need to know all the tags. It can be tiring to learn all attributes and other DITA elements. It is much easier if you only use a reduced number of them. The currently developed ‘Lightweight DITA’ approach addresses this problem by providing a list of recommended elements (which are a subset of all DITA tags).
2. The simplified topic-based approach
The next step, after learning how to create the content, is how to structure it in DITA. The basic ‘concept-task-reference’ topic types are sufficient for most documentation teams. As a rule of thumb, you can start converting your unstructured content by identifying the task topics, and then dividing any other text into concept and reference topics.
Figure 1. Two of the three views in oXygen XML Author; full tags or no tags.
Figure 2. Moving unstructured content into structured DITA topics.
From there, another easy approach could be that you select all specific information you have (for instance, tables, list of parameters, and similar data-heavy content) and put that information into reference topics. Anything left out will form your concept topics (see Figure 2 for the whole process).
Where are my heading styles?
When you get used to writing very long documents, you instantly miss the different heading styles you could use in Word to structure your content. In DITA, there are no headings. Instead, you can use your DITAMap file (a separate file, which functions as your table of contents) to reorganise your topics, thus creating the different ‘heading’ levels.
When you configure the final output, the different levels in the DITAMap function as heading levels. You can assign different styling to all levels receiving the desired output (see Figure 3).
To get even more flexibility, you can use the <section> tags in DITA topics. This
element can hold a <title> tag, so you can create additional subsections inside topics.
You just need one expert
In the previous paragraph, I started to scratch the surface of DITA by mentioning different tags and element levels. However, not all communicators need to know what they are actually using. As long as the content is valid and does not break any DITA constraints, then everything is fine.
To ensure that all communicators produce valid XML texts, you just need one communicator in your team who is happy to study DITA in more detail, and who can provide guidance to the other communicators if they encounter any issues.
Even the dedicated DITA person does not need to know much; for starters, it is enough if they know what to look out for in task topics (in terms of its XML structure), how conditional processing works in DITA (including or suppressing content based on attribute values), and how each topic type should look like (separating content accordingly). You can generally acquire these skills quite quickly.
3. The challenges of working with DITA
Task topics
When it comes to structuring content, it is very easy to identify task topics since they contain the procedure-based instructions. Deciding whether to put a piece of text into a reference topic or a concept topic is a bit trickier, because there is a thinner line between reference and concept topics.
On the other hand, the DITA structure of a task topic can create some problems: you can only use a limited number of tags in the content, and your description must only talk about the procedure itself without any related conceptual information (see Figure 4).
This can be quite challenging as traditional instructions often include a mixture of task and reference information while the DITA structure only leaves room for images and some strictly task-related information. Because of that, you must often simplify your task topic and move the extra information into new concept or reference topics.
Metadata and processing attributes
When you create a traditional printed user manual, that document is final; it will not be taken to pieces, nor will it receive special formatting based on post-processing attributes. Therefore, you know that what goes in will be exactly what comes out. It is not the case with DITA.
In the DITA framework, you will often encounter the term ‘processing attributes’. These attribute values govern inclusion and exclusion of topics, sections, paragraphs or terms in the final output. If you have a topic for multiple audiences, you much specify if you want to include or exclude a piece of content for the given audience.
The same difficulty applies to using extensive metadata. Metadata is crucial for DITA-based content, because you need to identify your topics in some way. One way of labelling topics is by using keywords that correspond to the topics’ contents. If you keep those topics in a component content management system (CCMS), then just by searching for a keyword you can find and edit topics very quickly.
Again, getting used to doing such micromanagement can be tiring to begin with.
Summary: your action plan
These are the first steps you should take when you start studying DITA:
- Find a good XML editor (that supports DITA) and learn its basic functions.
- Analyse your content and identify potential task topics. Those parts of the content
should be converted and rewritten first, finalising the rest of the content later. - Elect a dedicated resource who is responsible for the DITA conversion and adoption. It is enough if one person understands the more complex side of DITA. The others can rely on the expertise of the DITA ‘champion’, especially on issues related to the peculiar nature of some rules in DITA.
Adam Sanyo is a junior member of ISTC. He has four years’ experience in technical writing. He currently works for Amdocs in London. He is also trialling a technical writing and XML course at University of Debrecen in Hungary.
E: adamsanyo@gmail.com
LI: www.linkedin.com/in/adamsanyo