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.
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.
Use the prolog section to provide information like author, copyright and metadata.
Use sections to organize subsets of information that are directly related to a topic.
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.
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).
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).
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.
Use a link list to group multiple when the order of the links should be preserved in the published form.
Use a link pool to group multiple links that have common characteristics.
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.
Use screen to encode the textual representation of a computer screen or a window interface panel.
Use lines to encode a dialog, lists, text fragments, etc.
Use a message block to encode a multi-line message or multiple messages.
Provide an example that best illustrates or supports the current topic.
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.
Provide hazard warning information.
A figure defines a display context with an optional title and diverse content, which usually includes an image element.
Use an image map to define regions on an image that will link to different targets.
Use simple table for tables with regular structure and without a caption.
Provide a description that should be used as alternate content or displayed as hover help.
Use a simple list for items containing short, phrase-like content.
Normal paragraph content.
Preformated content, preserves line breaks and spaces.
Unordered list.
Ordered list.
A DITA table that can encode any complex table structure.
Use draft comment for simple review and discussion of topic contents.
Use section div as a container for section content with no associated semantics.
Use link information for a descriptive paragraph following the list of links.
Use the metadata section to provide information about the content and subject of this topic such as category, audience, keywords and product information.
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.
The topic title must clearly convey the content found in the topic.
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.
A body division (bodydiv
element) is a grouping element
within the topic body, without any explicit semantics.
A task topic tells users how to accomplish a task. Try to limit a task topic to a single procedure.
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.
The short description of a task should describe in a couple of sentences why the reader is performing the task.
In the pre-requisites section describe the things that a user needs to know or do before starting the task.
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.
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.
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.
Use the informal steps section to describe procedural task information that would not normally be described as steps.
Use the step section to provide expository text before the step element.
Use choices to inform the user to choose one of several actions while performing the step of a task.
Use a choice table provides to provide a series of optional choices.
Use the info element to provide additional information about the step.
Use tutorial information to provide additional information that is useful when the task is part of a tutorial.
Provide an example to illustrate this step of the task.
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.
Use the step result to describe the expected outcome of the current step.
Use the result section to describe the expected outcome of the task as a whole.
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.
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.
Use noun phrases for the concept title and try to place important words at the beginning to draw the users attention.
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.
A concept body division (conbodydiv
element) is a
grouping element within the concept body, without any explicit semantics.
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....
Use noun phrases for the reference title and try to include the name of the referenced information.
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.
A reference body division (refbodydiv
element) is a
grouping element within the reference body, without any explicit semantics.
Use the reference syntax section for syntax or signature content.
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.
Use a glossary group as a container for multiple glossary entries.
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.
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.
Use the glossary alternative to provide a variant term the same meaning as the defined term.
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.
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.
Use the required conditions to provide all required conditions that have to be fulfilled for performing a task.
Use the required personnel section to specify information on the personnel required for the task.
Use the support equipment list to provide the required support equipment for the task.
Use supplies to list any supplies required for the task.
Use the spares lists to provide the spare parts required for a task.
Use the safety session to list any safety condition that has to be taken in account for the task.
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.
Expand the title by providing additional information about the problem this topic provides solutions for.
Describe the state that the troubleshooting topic is intended to remedy.
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.
Describe briefly a potential source of the problem that this troubleshooting topic addresses.
Specify steps that should be followed in order to solve the problem.
Identify the party who is responsible for performing the remedy procedure.