For technical writers, the DITA standard represents three main things: a) a set of templates to follow, b) mechanisms for reuse and c) conditional publishing.
A Closer Look at the DITA Standard
Contrary to popular belief, DITA authoring is simple. DITA for writers is neither a tool nor a publishing format. It is a standard made up of roughly four distinct elements.
- A set of document templates: or rather, templated building blocks used to create your document. In DITA, these include generic structures and types such as procedure, concept, error recovery, and reference. The writers select a topic type before starting authoring.
- Reuse mechanisms: also known as the technical possibilities of reusing an entire topic, like a task section, fragments of text or images. The writers pick reusable content to integrate into the final document.
- Conditional publishing: the possibility of tagging contents with specific values and applying filters to the publication so that from a single set you can create more targeted manuals. The writers can select and apply filtering conditions on the content.
- Mechanisms of specialization and generalization: this possibility, unique to the DITA standard, is important but a bit more technical. We will talk about it later in the article. This is out of scope for the writer.
From the writer’s perspective, the first three points are the most important.
Topic Templates: What is the objective of this topic?
Each topic type has its own build structure with expected information. Think of standard templates for a procedure or an error recovery operation. What kind of information will the users expect? In these templates, we are likely to find:
- mandatory information (a title) and optional information (an image or a table)
- nested information, like in a numbered list (if you start a list, you need at least one item) or a list of steps
- a fixed sequence for the information, for example the prerequisites must be placed before the post-requisites, safety warnings must be placed before the instruction
The writers choose first the type of topic they wish to create and then simply follow the information model.
Possibility of Reuse, Simple and Complex
Reusing Topics
Ideally, each topic should be independent and autonomous. The topic does not need other information or topics to meet the need of the user, understand the functionality, or follow the end-to-end procedure. That is a basic principle of topic-based authoring.
The writer can use this topic in as many sections and document as they wish, and as many times as needed. Topic reuse is the easiest method of reusing content in DITA. If necessary, the writer can group several topics into a single cluster (or a map) and reuse those just as easily. The document where the topic architecture is stored is another DITA object called a map. It mimics a table of contents. The map is the object that will be published to web, print and mobile outputs.
Content Fragment Reuse
You can reinsert a sentence or even a single word in the topic. Good candidates for fragment reuse might be a fixed and repeated installation step, a safety warning, or a product name or interface name. The intention is to ensure content consistency and facilitate the updating of critical information.
Using Filters for Conditional Publishing
Some content may only be applicable in certain cases or for certain user profiles. For example, you can write an installation step for Linux and Windows, and then identify the specific information for each platform. When publishing the final document, simply choose what you want to filter to produce two separate documentary sets: one for Linux and one for Windows. Another example is producing training material by noting which information is specific to the trainer. For example; tips or exercise results. When publishing, you might choose a manual for students (without trainer-specific information), and a trainer manual including all information.
DITA Is neither a Language nor a Tool—It’s an Open Standard
An open standard is a format with publicly available specifications and no access barriers on costs and specifications formats. It’s both free and readable freely. DITA specifications are therefore available online and written in an open language like HTML or TXT.
It is this characteristic that allows many publishers to create software and solutions around the DITA open standard. The format used for your content (DITA XML) is independent from the editing and managing tools, thus guaranteeing the portability, longevity, and interoperability of content.
Is XML Difficult to Use?
XML is an open, tagged computer language, just like HTML. Open an HTML document alongside an XML document and you will find many similarities.
Elements and Attributes
Elements are used as the main building blocks for the information. They will be used for titles, paragraphs, images, bulleted lists, notes, etc. Attributes are used to refine the elements, by specifying the language or adding the size of an image.
Don’t Want to Look at Code?
Most XML editors that include DITA provide a view with or without tags. Sometimes it is very simplified. Web tools, in particular, offer a simplified XML authoring experience.
To Form or not to Form
Some authoring tools can also model content in a way that presents forms to users, which they can then fill out with ease.
Did you notice we did not talk about tools, publications, or version control? The DITA standard does not give any obligations on these aspects.
This explanation is highlighting only the most important part of the standard. For further information about key reuse, DITA training, information modeling, taxonomy and metadata, constraints, and DITA management systems, please contact our experts!
**
As promised, here is a short explanation on specialization:
Specialization and Generalization
When generic models of procedure, concept, and error recovery are not appropriate for content, you can refine and extend these templates through a DITA specialization. Generalization is the fall-back system that allows the content to return to non-specialized (generic) content. In general, after content analysis, DITA experts and information architects will be able to advise whether or not there is a need for specializations.
If you specialize using DITA, your content will stay consistent with the standard. Imagine you wanted to share your DITA content with another company, a client or supplier. They could either use it “as is” after exchanging specializations (often in the form of an XML schema/DITA plugin), or ask you to generalize the content to feed it in their own tools and documentation. In this case, the generalisation mechanism removes the specifics from your content and returns it to a non-specialized (generic) state.
