Hints for DITA elements

Common topic elements

abstract

The abstract section is useful in general when the content that you want to place as the initial paragraph of a topic cannot be placed in a short description, for example in case it contains lists or tables. If the same content can be placed within a short description then use a shortdesc element instead.

titlealts

Use alternate titles to provide a specific title that should be used in creating a table of contents (for navigation) or a title specific to search results. When there are no alternate titles, the topic title is used for all title purposes.

prolog

Use the prolog section to provide information like author, copyright and metadata.

section

Use sections to organize subsets of information that are directly related to a topic.

codeblock

Use a code block to mark lines of program code. Whitespace inside a code block will be preserved and the output rendering is usually done with a monospaced font.

dl

Use a definition list to provide definitions for specific terms. The term is specified in a definition term (dt element) and the definition is marked with a definition description (dd element).

parml

Use a parameters list to mark up parameters and their definitions. A parameter is is specified in a parameter term (pt element) and the definition is marked with a parameter description (pd element).

syntaxdiagram

Use a syntax diagram as a container for all the syntax elements that make up a syntax definition representing the syntax of a statement from a computer language, or a command, function call or programming language statement.

related-links

linklist

linkpool

Use a link pool to group multiple links that have common characteristics.

lq

Use long quote to indicate content quoted from another source. For short, inline quotations use the q (quote) element instead. Use the href attribute to store a URL to the source of the quotation.

screen

Use screen to encode the textual representation of a computer screen or a window interface panel.

lines

Use lines to encode a dialog, lists, text fragments, etc.

msgblock

Use a message block to encode a multi-line message or multiple messages.

example

Provide an example that best illustrates or supports the current topic.

note

Use note to enter information, differentiated from the main text, which expands on or calls attention to a particular point. The type attribute can be used to specify the note type like caution, important, etc.

hazardstatement

Provide hazard warning information.

fig

A figure defines a display context with an optional title and diverse content, which usually includes an image element.

imagemap

Use an image map to define regions on an image that will link to different targets.

simpletable

Use simple table for tables with regular structure and without a caption.

desc

Provide a description that should be used as alternate content or displayed as hover help.

sl

Use a simple list for items containing short, phrase-like content.

p

Normal paragraph content.

pre

Preformated content, preserves line breaks and spaces.

ul

Unordered list.

ol

Ordered list.

table

A DITA table that can encode any complex table structure.

draft-comment

Use draft comment for simple review and discussion of topic contents.

sectiondiv

Use section div as a container for section content with no associated semantics.

linkinfo

Use link information for a descriptive paragraph following the list of links.

metadata

Use the metadata section to provide information about the content and subject of this topic such as category, audience, keywords and product information.

DITA Topic elements

topic

Use a generic DITA topic only if the content cannot be placed into one of the other more specialized topic types, like task, concept, reference, etc.

title

The topic title must clearly convey the content found in the topic.

shortdesc

Use the short description to expand the title, providing additional information about the content of the topic. It should always be composed of complete sentences and form a comprehensive thought.

bodydiv

A body division (bodydiv element) is a grouping element within the topic body, without any explicit semantics.

DITA Task elements

task

A task topic tells users how to accomplish a task. Try to limit a task topic to a single procedure.

title

Use an imperative verb form for the task title to help users distinguish between topics that tell how to complete the task and other topics that might only provide conceptual information about the task.

shortdesc

The short description of a task should describe in a couple of sentences why the reader is performing the task.

prereq

In the pre-requisites section describe the things that a user needs to know or do before starting the task.

context

The context section allows you to provide short background or high-level information about the task or its larger workflow. You can also mention here any warnings or general pitfalls with regard to the task.

steps

Use a numbered step procedure (steps) to describe the actions that the user must perform in a specific order. Alternatively, use a bulleted step list (steps-unordered) to describe actions that the user can perform in any order.

Each step describes an action that a user must follow to accomplish a task. Enter the instructions as a direct command in the required cmd element. A step can also optionally contain different information, sub-steps, step example, choices or a step result.

steps-unordered

Use a bulleted step list (steps-unordered) to describe actions that the user can perform in any order. Alternatively, use a numbered step procedure (steps) to describe the actions that the user must perform in a specific order.

Each step describes an action that a user must follow to accomplish a task. Enter the instructions as a direct command in the required cmd element. A step can also optionally contain different information, sub-steps, step example, choices or a step result.

steps-informal

Use the informal steps section to describe procedural task information that would not normally be described as steps.

stepsection

Use the step section to provide expository text before the step element.

choices

Use choices to inform the user to choose one of several actions while performing the step of a task.

choicetable

Use a choice table provides to provide a series of optional choices.

info

Use the info element to provide additional information about the step.

tutorialinfo

Use tutorial information to provide additional information that is useful when the task is part of a tutorial.

stepxmp

Provide an example to illustrate this step of the task.

substeps

Use sub-steps to break a step down into a series of separate actions. This should be used only if necessary and if you need to use more than one level of sub-step nesting, you should probably rewrite the task to simplify it.

stepresult

Use the step result to describe the expected outcome of the current step.

result

Use the result section to describe the expected outcome of the task as a whole.

postreq

If needed, add a sentence about the next task that the reader must perform to complete the overall workflow, and if possible, provide a link to the relevant topic.

DITA Concept elements hints

concept

Use the concept topic to provide overview and background information that helps end users understand essential information about a product, interface, task, etc. A concept topic typically answers a What is... question.

title

Use noun phrases for the concept title and try to place important words at the beginning to draw the users attention.

shortdesc

When writing short descriptions for concepts, try to include a summary of the main point of the content and tell the user why this information is important to understand.

conbodydiv

A concept body division (conbodydiv element) is a grouping element within the concept body, without any explicit semantics.

DITA Reference elements hints

reference

Use a reference topic to provide "look-up" information that end users might need to refer to. A reference topic may answer questions like How Much..., How Many..., or What Form....

title

Use noun phrases for the reference title and try to include the name of the referenced information.

shortdesc

When writing short descriptions for references, try to describe what the reference item does, what it is, what it is used for and what specific type of information is provided in this topic for each referenced item.

refbodydiv

A reference body division (refbodydiv element) is a grouping element within the reference body, without any explicit semantics.

refsyn

Use the reference syntax section for syntax or signature content.

properties

Use properties table to give a list of properties for the subject of the current topic. Each property can include the type, value, and a description.

Glossary

glossgroup

Use a glossary group as a container for multiple glossary entries.

glossentry

Use a glossary entry to define a single sense of a glossary term. If the same term has multiple senses, create a separate glossary entry for each sense.

glossScopeNote

Use the scope note as a clarification of the subject designated by the glossary term, such as examples of included or excluded companies or products.

glossAlt

Use the glossary alternative to provide a variant term the same meaning as the defined term.

Machine industry

prelreqs

Use the preliminary-requirements section to document things the user needs to know or do before starting the current task. This is similar to prereq but contains a more descriptive content model.

closereqs

Use the closing requirements section to describe steps or tasks that the user should do after the successful completion of the current task. This is similar to postreq but contains a more descriptive content model.

reqconds

Use the required conditions to provide all required conditions that have to be fulfilled for performing a task.

reqpers

Use the required personnel section to specify information on the personnel required for the task.

supequip

Use the support equipment list to provide the required support equipment for the task.

supplies

Use supplies to list any supplies required for the task.

spares

Use the spares lists to provide the spare parts required for a task.

safety

Use the safety session to list any safety condition that has to be taken in account for the task.

Troubleshooting

troubleshooting

A trobleshooting topic tells users how to apply corrective action to solve a problem. It begins with a description of the condition the user may want to correct followed by cause-remedy pairs that represent potential solutions.

shortdesc

Expand the title by providing additional information about the problem this topic provides solutions for.

condition

Describe the state that the troubleshooting topic is intended to remedy.

troubleSolution

Describe a potential solution to solve the problem.

A solution contains cause and remedy information. The cause might be omitted if it is implicit or if the remedy is not associated with a cause. The remedy might be omitted if there is no known remedy for the cause.

cause

Describe briefly a potential source of the problem that this troubleshooting topic addresses.

remedy

Specify steps that should be followed in order to solve the problem.

responsibleParty

Identify the party who is responsible for performing the remedy procedure.