Jump to main content
About The DITA Style Guide
As more companies implement DITA to streamline the development of technical content, the demand for DITA-literate technical communicators is growing. The DITA Style Guide provides comprehensive, practical explanations of DITA elements and attributes. Real-world examples and clear recommendations show you how to create consistent, semantically-correct DITA content.
The role of a style guide
A style guide provides advice on the optimal use of approaches, procedures and processes. A DITA style guide focusses on best practice application of the DITA standard.
Acknowledgements
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
Content models and information types
A content model is a framework that represents the structure of the information to be stored. In DITA, a content model is implemented as an information type, or topic type.
Information types
A fundamental principle of DITA is information typing, which categorises information according to the nature of the content. The three base DITA information types are concept, task and reference.
What is a topic?
A topic in DITA is an independent chunk of information covering a single idea or task, authored as a unit, and stored in its own file. Topics are categorised by information type. DITA's topic-based architecture enables the same topic to be used in different publications.
Working with topics
Specialised information types
Specialised information types provide a topic architecture that closely matches the structure of your content.
Topic exemplars
Purpose of ditamap files
DITA map files are used for defining the topics of a publication, specifying the topic sequence, and controlling linking between topics.
Topic manifest
Any topics referenced anywhere in the ditamap will be processed into the output publication.
Topic hierarchy
In DITA, the sequence and hierarchy of the topics to be published are defined in the ditamap through nested topicref elements.
Relationship tables
Relationship tables are used to store linking relationships between topics in a collection in the ditamap, rather than in individual topics. Linking relationships are defined in a table-like structure, with rows in the table determining which topics are linked to which.
Linking relationships
DITA encourages the linking relationships to be stored outside the topic content. Links can be generated from topic hierarchies, relationship tables, and related-links section links.
Inheritance and cascades in ditamaps
Properties in ditamaps sometimes cascade from parent elements to child elements. Some values in ditamaps also override the equivalent values in referenced topics.
Embedded (or nested) ditamaps
The technique of using embedded, or nested, ditamaps can make it easier to manage documents by separating complex collections of topics into a number of smaller, simpler collections.
DITA map vocabulary
The bookmap feature
Bookmaps are a specialisation of the base DITA map information type. Like ditamaps, bookmaps are containers for structure and context metadata, and do not contain any content. Bookmaps are used to describe page layout publishing outputs such as books, articles, manuals and research papers. They contain information structures that are specific to linear publications, such as tables of figures, title pages, chapters, sections and parts.
Organisation of DITA elements
Elements in DITA are grouped together into a number of categories for organisational and comprehension purposes.
Working with mark-up
Element domains
Elements in DITA are arranged into domains for organisational purposes and technical reasons.
Short descriptions
The short description (or shortdesc) is arguably the most important component of a DITA topic, and is also one of the most difficult elements to write. Short descriptions should be written for every topic.
Lists
The purpose of a list is to make it easier for the reader to understand sequences of information and collections of like information. Different types of lists are used for different information structures.
Paragraphs
Paragraphs are the basic components of topics. A paragraph (p) element should be a self-contained unit dealing with one idea or point, typically expressed in two or more related sentences. The p element should be used when no other semantically-specific block element is available.
Procedures and steps
The purpose of procedural documents is to explain to the reader how to accomplish tasks. The task information type is specifically designed for procedures, with a well-defined structure built around steps.
Tables
The purpose of a table is to structure, organise and present factual data that a user will need to look up or reference. There are two general purpose table types in DITA: table and simpletable.
Phrases
The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
Special characters and dates
Avoiding writing for output
Do not include formatting information in your DITA content topics.
Stem sentences, glue text, and other transitional information
Transitional information, such as stem sentences, is largely redundant in DITA's minimalist, topic-based, semantic mark-up architecture. The role of transitional information in contextualising the content has been eliminated through the use of smaller chunk sizes, meaningful titles, information typing, structure, and demarcation labels automatically-generated in the output.
Punctuation in lists
Ordered and unordered list items should have no terminating punctuation marks, such as commas, semicolons, and full stops, except when all items in a list are complete sentences. This approach maximises re-usability.
Titles and headings
Titles are used in a number of mark-up structures in DITA. Titles are a mix of content and metadata. The mark-up in titles should be kept as simple as possible, and workarounds to achieve specific formatting outcomes should not be used.
Crafting paragraphs
A paragraph should contain one unit of thought or action, or main point, and should be typically three to eight sentences in length. All of the sentences in a paragraph should relate to its main point.
Different languages
The xml:lang attribute stores the human language of the content, and can be applied to any DITA element.
Quotation marks
Quotation marks should not be included in DITA content. The marks should be added, if required, during the publishing process.
Figures and images
Images are placed in topic content using the image element. The image element can stand alone, or can be contained within a figure (fig) element.
Image file formats
Where there is no strong reason to choose another image file format, you should use SVG or PNG file formats in DITA topics.
Image alignment, placement, and sizing
The align, placement, width, and height attributes of the image element are used to specify the placement and size of images when generated to an output delivery format.
Images in titles
Images in topic, figure, and other titles, while technically valid, should not be used.
Callouts
Callouts with keys, rather than text labels, should be used when identifying parts of an illustration.
Localising graphics
Where possible, graphics that include text should be managed in SVG format to simplify localisation.
Multimedia in DITA topics
The object element is used to embed multimedia in DITA topics.
Figures containing tables
Simple tables can be contained within figures instead of, or in addition to, images.
Image maps
The imagemap element is used to define image maps (hotspot graphics) in DITA topics.
WAI compliance
So that output from your DITA source meets accessibility responsibilities, you must include alternative text representations of all images in DITA content.
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Types of cross-references
A cross-reference is used in DITA to link or associate one piece of content with another. The cross-reference (xref) element is the primary mechanism for cross-referencing, but other elements also have cross-referencing functions.
The xref element
The cross-reference element is used for linking or otherwise cross-referencing text within a topic to other topics, elements within a topic, or resources external to the DITA collection.
Avoiding in-text cross-references to topics
Cross-references to other topics should be stored in the relationship table of the ditamap, external to the topic, and not in-line within the text of the topic.
Cross-referencing topics and external resources
Cross-references are commonly made to other DITA topics in a collection, and to information resources outside the collection. These external targets can be any type of electronic resource that can be addressed through a URI, including e-mail addresses, documents on a network file server, and Web content.
Cross-referencing elements in a topic
Cross-references to elements within topics such as figures and tables allow a reader to easily navigate through a document, whether it is in a page layout format or a hypertext format. The xref element is always used for cross-referencing elements within a topic.
Links in related-links sections
When a topic requires cross-references to other topics where those cross-references will always be valid in the context of the topic, they should be contained within a related-links section after the topic body. In all other cases, cross-references should be defined in the relationship table of the ditamap.
Managing cross-references
Cross-references in titles
You should not use cross-reference elements within topic titles.
Content re-use definition
Content re-use is a means of improving efficiency by eliminating repetition of phrases, blocks of text, topics, and even collections of topics.
Re-use and the DITA Maturity Model
Content re-use is one of the features that you should adopt early in your move from style-based authoring to structured authoring with DITA.
The content reference (conref) attribute
The conref feature allows DITA content to be used in any number of different places in a collection. The conref attribute in a referencing topic specifies the source topic and the element within that topic to re-use.
Re-use practices
Variables
Organising re-use topics and elements
Embedded topics and ditamaps
The ditamap is a powerful tool for re-using topics in different output publications. Topics can also be re-used using ditabase topics, but you should avoid this technique.
Advanced conref principles
Conditional processing concepts
When DITA content is processed to a reading format, rules to exclude or highlight some of the content can be defined in a ditaval file. This conditional processing requires metadata attributes to be set on DITA elements that may possibly be excluded or highlighted.
Condition (or select) attributes
The audience, platform, product, otherprops and rev attributes can be applied to most DITA elements. They are used for conditional processing, and are known as the condition (or select) attributes.
Filtering and flagging
Content marked with metadata attributes can be conditionally processed so that the content is filtered (excluded) or flagged (highlighted) in the published output.
Other metadata
In addition to the select attributes, DITA content includes many forms of metadata. These metadata elements and attributes are used to manage and organise topics, ditamaps and publications.
Indexing
DITA incorporates powerful features for indexing, including multi-level indexing, and see and see-also redirection. Index entries can be applied in the ditamap, in the topic prolog, and inline within the topic content.
Structured authoring documentation stages
The documentation process within a DITA workflow can be separated into stages of building, associating, and publishing.
Unit testing in a team
A process where multiple authors are working on a large repository of topics can make it difficult to manage the quality and consistency of the content. Unit testing is a technique to identify validation errors earlier in the documentation process.
Restricting authors and limiting element choices
To make it easier for authors to choose semantic mark-up elements, it is possible to reduce the number of elements available for selection. This restriction can be managed by an authoring tool, or through the constraints mechanism introduced in DITA 1.2.
File and folder naming conventions
Using an organisation-wide, well-documented file naming and folder structure convention will improve the usability of the authoring process for DITA authors, especially those working in a team.
Elements for pre-publish review
The draft-comment element allows review and discussion information to be embedded within topic mark-up. The more basic XML comment can also be used for a similar purpose.
The DITA publishing process
XSL-T and XSL-FO are the technologies that underpin most DITA publishing tools.
Page numbering in page layout documents
A single page number sequence through an entire page layout document generated from DITA is often preferable to the traditional system of different page number sequences for front matter and back matter.
Content Management Systems
Although it is possible to create, manage and edit content in DITA without a CMS, it is invariably easier with the aid of a CMS.
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.
Introduction to DITA
DITA is an XML standard, an architectural approach, and a writing methodology, developed by technical communicators for technical communicators.
Distinction between format and style, and data and metadata
In DITA, format has a different meaning to style. Likewise, the meanings of data and metadata are very different. These distinctions in meaning are important to understanding the broader concept of the separation of content and form.
Specialisation
Specialisation allows you to construct your own types of documents without losing the benefits of working within a DITA framework; in particular, you can maintain interchangeability.
Generalisation
When information in a specialised information type needs to be converted into the information type from which it was specialised, the process is known as generalisation.
Constraints
The constraints mechanism in DITA allows the use of elements and attributes in an information type to be restricted without needing to create a full specialisation. Constraints aim to simplify the authoring process by reducing the complexity of an information type.