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.

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.

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.

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.

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.

Specialised information types provide a topic architecture that closely matches the structure of your content.

DITA map files are used for defining the topics of a publication, specifying the topic sequence, and controlling linking between topics.

Any topics referenced anywhere in the ditamap will be processed into the output publication.

In DITA, the sequence and hierarchy of the topics to be published are defined in the ditamap through nested topicref elements.

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.

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.

Properties in ditamaps sometimes cascade from parent elements to child elements. Some values in ditamaps also override the equivalent values in referenced topics.

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.

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.

Elements in DITA are grouped together into a number of categories for organisational and comprehension purposes.

Elements in DITA are arranged into domains for organisational purposes and technical reasons.

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.

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 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.

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.

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.

The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.

Do not include formatting information in your DITA content topics.

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.

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 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.

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.

The xml:lang attribute stores the human language of the content, and can be applied to any DITA element.

Quotation marks should not be included in DITA content. The marks should be added, if required, during the publishing process.

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.

Where there is no strong reason to choose another image file format, you should use SVG or PNG file formats in DITA topics.

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 topic, figure, and other titles, while technically valid, should not be used.

Callouts with keys, rather than text labels, should be used when identifying parts of an illustration.

Where possible, graphics that include text should be managed in SVG format to simplify localisation.

The object element is used to embed multimedia in DITA topics.

Simple tables can be contained within figures instead of, or in addition to, images.

The imagemap element is used to define image maps (hotspot graphics) in DITA topics.

So that output from your DITA source meets accessibility responsibilities, you must include alternative text representations of all images in DITA content.

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 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.

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-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-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.

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.

You should not use cross-reference elements within topic titles.

Content re-use is a means of improving efficiency by eliminating repetition of phrases, blocks of text, topics, and even collections of topics.

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 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.

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.

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.

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.

Content marked with metadata attributes can be conditionally processed so that the content is filtered (excluded) or flagged (highlighted) in the published output.

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.

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.

The documentation process within a DITA workflow can be separated into stages of building, associating, and publishing.

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.

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.

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.

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.

XSL-T and XSL-FO are the technologies that underpin most DITA publishing tools.

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.

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 is an XML standard, an architectural approach, and a writing methodology, developed by technical communicators for technical communicators.

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 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.

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.

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.