How to write in DITA

How to write in DITA
Anindita Basu

@anindita_basu
Learning goals
• Understand how DITA is similar to and different from other authoring
frameworks
• Plan and model a document
• Determine the DITA tags you are most likely to use in your day-to-day
work
• Write in DITA

@anindita_basu
HTML authoring frameworks
• Difficult to make global changes
• Difficult to handle both new and legacy information
• Difficult to determine information completeness
• Difficult to share across product groups or external partners

@anindita_basu
XML authoring frameworks
• Open standards
• Separation of form from content
• Extensible and meaningful tags
• Tools ecosystem

@anindita_basu
An XML DTD and architecture developed specifically for technical content

@anindita_basu
DITA extends the generic advantages of XML
• Link management
• Conditional processing
• Re-use

@anindita_basu
DITA topic types
• Every topic is a complete topic.
• Every topic answers one — and only one — type of question.

@anindita_basu
DITA topic types
• Concept
How does this work? Why should I do this?
• Task
How to do this?
• Reference
What else might I need to know?

@anindita_basu
DITA tags
• DITA tags are mostly specific to the DITA topic types
• Some DITA tags can be used in any topic type
• Every DITA topic needs some tags that are essential

@anindita_basu
DITA tags
HTML DITA
<title> <title>
<h1>, <h2> … <h6> <title>
<ol> <ol>, <steps>
<li> <li>, <step>, …
<p> <p>
<img> <image>, <fig>
<table> <table>

@anindita_basu
DITA tags
All topic types have the same basic structure:
• ID
• Title
• Body

@anindita_basu
DITA tags
• Concept
Text, images, lists, tables, and contained within sections that can have individual titles.
• Task
Prerequisites, steps, results, and post-requisites. Also, text, images, lists, and tables.
• Reference
Text, images, lists, and tables.

@anindita_basu
DITA tags
<shortdesc>
<taskbody>
<title><task>
<context>
<steps><prereq> <example>
<result> <postreq>
The order of
the tags is
important!

@anindita_basu
DITA maps
Maps show the relationships and the connectivity for a set of disparate
objects that are otherwise stand-alone entities.

@anindita_basu
DITA maps
• Specify which of the topics must be shown in a table of contents
• Specify which of the topics need to be build for a specific output
• Define links between related topics

@anindita_basu
DITA maps
Automatic link generation:
• Sequence
• Family

@anindita_basu
DITA maps
Topics in a row:
• Default behaviour: Each topic in a column has links to all topics in the other
columns of that row, and vice versa.
• Source-only linking: A topic in one column links to the topics in the other
columns but the topics in the other column do not link back to the linking
topic.
• Target-only linking: A topic in one column has links from topics in the other
columns but does not link to them.

@anindita_basu
DITA maps
Topics in a cell:
• The topics within a cell do not link to each other but all topics in one
cell of a column link individually to all topics in another cell of a
column.
• To make the topics within a cell to link to each other, you must specify
a collection-type attribute for the cell.

@anindita_basu
Reuse in DITA
• Content reuse: Reusing the content itself
• Design reuse: Reusing the design of the content
• Process reuse: Reusing the process by which DITA content is
generated

@anindita_basu
DITA conref
• Every element has a 'conref' attribute.
• This attribute points to any other equivalent element in the same or
any other topic.
• It is a link that establishes a use-by-reference relationship.
• This relationship allows content from one topic to be referenced in
multiple places.

@anindita_basu
DITA and SEO
Search engines:
• Focus on specific tags in the text
• Do not understand images
• Are confused by tables

@anindita_basu
DITA and SEO
• Never leave the <title> element blank.
• Use the <searchtitle> tag for a more wordy and descriptive title.
• Always give a meaningful <shortdesc>. Never leave it blank.
• Always provide ALT text for images.
• Always provide a table summary (<desc>).
• Never have an orphan topic. (use relationship tables).

@anindita_basu
Best practices
Concept Task Reference
Must
have
• At least one
paragraph
• A link to a task topic
• Context
• Steps
• At least one
paragraph
• A link to a task
topic
Nice to
have
• Conceptual diagram • Results
• What to do next
• A link to a
troubleshooting
topic
• UI description
• Field-value
tables,
parameters, …
Review • Description of the UI
• Numbered lists with
instructions
• Description of the
UI
• Field-value tables
• Conceptual
information

@anindita_basu
Best practices
• One single file for all conrefs
• Topic linking through DITA maps only

@anindita_basu
Best practices
• The writing "thinking" needs a complete reorientation.
• Semantic tagging takes a while to get used to.
• Short descriptions are often the hardest 2 - 3 sentences to write in
any topic.

How to write in DITA

Recommended

Recommended

More Related Content

Similar to How to write in DITA

Similar to How to write in DITA (20)

More from Anindita Basu

More from Anindita Basu (7)

Recently uploaded

Recently uploaded (20)

How to write in DITA

Editor's Notes