This session provides insights into how to create documentation using DITA. At the end of the session, the audience should be aware of the procedures and best practices when applying DITA.
2. @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
4. @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
10. @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?
13. @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
18. @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.
23. @anindita_basu
DITA maps
Maps show the relationships and the connectivity for a set of disparate
objects that are otherwise stand-alone entities.
24. @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
35. @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.
36. @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.
39. @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
40. @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.
44. @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).
46. @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
49. @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.
Editor's Notes
Icebreaker: Read the handout
Exercise 2: Create a manual
Song exercise
Exercise 3: Recast the manual according to the topic types
Exercise 4: Mark the manual up with DITA tags
Exercise 5: Look at your ToC and think about links.