DITA Surprise, Unwrapping DITA Best Practices - by Nolwenn Kerzreho, Technical Account Manager for Europe - tekom tcworld 2016

1. DITA Surprise,
Unwrapping DITA
Best Practices
Nolwenn Kerzreho, IXIASOFT
Technical Account Manager for Europe

2. Your presenter today
Nolwenn Kerzreho
• Started using & teaching DITA in
2009
• IXIASOFT Technical Account
Manager for Europe (DITA CMS)
• Master’s degree in translation
management, terminology,
project management and
technical writing
• @NolwennIXIASOFT
• #Tekom16 #tcworld16

3. Agenda
• Reminder… DITA is an open standard used
worldwide
• Best practices
 Topic-based authoring & templates
 Syntax and metadata & best practices
 Reuse topics, blocks, texts – do more with less
 Multichannel delivery
 Collaboration with engineers, translation vendors and
more
• Success stories
• What next?

4. DITA is being adopted worldwide
Keith Schengili-
Roberts
DITAWriter.com

5. DITA is being adopted worldwide
Keith Schengili-
Roberts
DITAWriter.com

6. TOPIC-BASED AUTHORING
A topic is a small, self-sufficient piece of information, with a clear
objective and a set structure.

7. Topic-based authoring
“Authoring an information set as a collection of
discrete units called topics, rather than as a whole
book or help system.”
– Mark Baker, The Language of Technical Communication
Benefits…
• Easy for readers to recognize
• Consistent
• Easy for writers to maintain and keep up-to-date
• Has a derived structure

8. Examples – description

9. Examples – task

10. Examples – reference

11. Other examples
of topic-based methods
• Simplified Technical English separates descriptive
writing and procedural writing…
• SCORM separates overviews, lessons, exercises
and quizzes…
• Information Modeling® separates tasks,
processes, descriptions…
What about your
content?

12. Finding out the underlying structure
• Recognize repeatable structures
• Find out the primary goal of each topic structure
 How to do something
 Explain an unfamiliar concept or tool
 List content for later use (part lists, menu enumeration,
error messages)

13. Example – procedures
How to write… a task
• Title
• Possibly a context
• Steps + warnings
• Images
• Example
• Results
Doing something to…
When… then…
Requires…
Danger:
1. Do this..
2. Do that…
3. Check…
Results
4. If not… do this…
Result is…

14. Example – troubleshooting
How to write… a
troubleshooting topic
Doing something to…
Condition:
Cause:
Remedy:
1. Do this..
2. Do that…
3. Check…
Results
4. If not… do this…
Result is…

15. SYNTAX AND METADATA
Syntax-rich information for people and machines…

16. Tags separate content from formatting
• Tag language to separate content and format
 Removes tedious (and inefficient/expensive) hand-
tweaked formatting associated with desktop publishing
 Removes DTP conversions back and forth
 Technical writers focus more on needs of users
 As a source format, facilitates better communication with
your users/vendors

17. Layout is applied automatically
TitleBlueBoldItal
ic
Paragraph:Times
12
Flag word:Tip!
Bold-Checkbox…
Title
Paragraph
 TIP!
Title
Paragraph Button
Tip
Title2:Bold
Paragraph:Times
12
Flag word:Tip!
Bold…
Title
Paragraph
TIP!
Content + stylesheets + formatting

18. Writers focus on content
• The writers focus on content and not how it looks
(styles and layout).
• The expected information is displayed to the
writers who fill in the missing text in wysiwyg
editors.
• Structure is provided for entire topics (task) but
also for smaller elements, such as sections,
figures and hazard statements.

19. Best practice – Hazard statement
Hazard statement structure
• Complies with ANSI Z535 and ISO 3864
• Danger/Warning/Caution/Notice
<hazardstatement type=“warning">
<messagepanel>
<typeofhazard>Rotating blade.</typeofhazard>
<consequence>Moving parts can crush and cut.</consequence>
<howtoavoid>Follow lockout procedure before
servicing.</howtoavoid>
</messagepanel>
<hazardsymbol href="rotatingblade.png"/>
</hazardstatement>

20. Best practice – Hazard statement
Hazard statement structure
• Complies with ANSI Z535 and ISO 3864
• Danger/Warning/Caution/Notice
<hazardstatement type=“warning">
<messagepanel>
<typeofhazard>Rotating blade.</typeofhazard>
<consequence>Moving parts can crush and cut.</consequence>
<howtoavoid>Follow lockout procedure before
servicing.</howtoavoid>
</messagepanel>
<hazardsymbol href="rotatingblade.png"/>
</hazardstatement>

21. Best practice – image display
The figure element encapsulates
• Title
• A pointer to an image
• An alternative text (Web accessibility rules)
Alternative text is explanatory text for screen-
readers. Visually-impaired customers will read a
description of the image.
WAI / WCAG rules in the list of resources

22. Metadata – data about the data
“Labels and catalogue information are part of a
topic's or collection's metadata.
Metadata allows content to be filtered, sorted,
processed, and otherwise manipulated. Choosing
accurate labels will result in more flexible
documents.”
- Dr. Tony Self, the DITA Style Guide

23. Metadata for cataloguing

24. Best practice – Metadata
• Maps & topics headers can contain metadata
when transformed to HTML
• Dublin Core metadata are compliant to
ISO Standard 15836:2009
ANSI/NISO Standard Z39.85-2012
• Adaptability for additional metadata / custom
metadata
• Machine interpretation and SEO

25. Best practice – Short descriptions
SEO is enhanced through titles and short
descriptions
• Akin to pyramidal writing for the web & journalist
style
• Not a summary or a repeat of the title
• Minimalism: make the content findable
Must answer the user’s question:
“Will this topic answer my question?”

26. Short descriptions
The transform can change the short descriptions
into a popup or display them near the title.
• Short descriptions are very useful for SEO
(Search Engine Optimization)
• Helps users locate the content they need
• Complies with the accessibility recommendation
for web content

27. Example – Short description
Design Considerations for Connecting Device I/O to
HPS Peripherals and Memory
One of the most important considerations when
configuring the HPS is to understand how the I/O is
organized in the Arria® 10 SoC devices.

28. REUSING CONTENT

29. Reusing entire topics
Create new documents with the certainty that the
updates will cascade…
Create more focused documentation for the right
product, the right user profile, the right deliverable
Installation
manual
Downloading
your first podcast
User
manual
Repair
manual
Kick-start

30. Reusing entire topics
Create new documents with the certainty that the
updates will cascade…
Create more focused documentation for the right
product, the right user profile, the right deliverable
Installation
manual
Downloading
your first podcast
User
manual
Repair
manual
Kick-start

31. Reusing sections and terms
• Reuse repeated terms: product and features
names, interface elements, menus …
• Reuse repeated “blocks”: note, bulleted list, safety
warnings, steps
• Consistency is essential for processing and
translation
Requires an excellent analysis of your
documentation

32. Let’s check!
Do you recall examples in your
documentation?
Think of duplicated information… entire topics,
sections, or phrases

33. DELIVERY
Future-proof and adaptive outputs

34. Multichannel publishing
“Web content professionals must think about
the findability and usability of their content, as
it is no longer enough to think about how to
create content.”
- Gerry McGovern, in What is the Job of the Web Content Professional?

35. Web & digital delivery
“81% of Chief eXperience Officers
expect to see more digital interaction
with customers by 2020”
Kapost – Consistency, Content, and Connection in the Age of the
Customer

36. Deliverable to…
• Print formats
• Embedded Web / mobile deliveries
• Context-sensitive help
• Dedicated merchant portals
• Internet of things

37. ADAPTING &
COLLABORATING
Taking it to the next level

38. Adaptation & Specializing
• Adapting to your needs & own information types
 Conditional publishing
 Reuse through direct references and indirect references
 Specializing / constraining
 Related models, such as machinery task, learning task,
etc.

39. Collaboration & tooling
• Interoperability:
 Reuse someone else’s content; merge contents…
 Large choice of tools: editors, content management
systems, dynamic delivery tools…
• Collaborate with subject matter experts, reviewers,
and translators
• Collaborate with translation management systems
and vendors
DITA interoperability session!

40. So what do you need?
• Prepare – analyse content & outputs, create an
overall plan
• Convince – create a content proof of concept
• Test – test tools & reused content
• Organise – which templates?
When to reuse?
Who decides?

41. Examples of success stories?
• Best: listen to organizations’ stories – the bad and
the good
• Here in tekom/tcworld…
 DITA Forum
 Users’ presentations
 Vendors’ presentations

42. Your opinion is important to us! Please tell us what you thought of the
lecture. We look forward to your feedback via smartphone or tablet under
http://ta09.honestly.de
or scan the QR code
The feedback tool will be available even after the conference!
Questions and Answers
Blog www.ixiasoft.com/en/news-and-events/blog
Twitter @IXIASOFT

43. Further readings
• Selection of organizations using DITA by Keith
Schengili-Roberts
http://www.ditawriter.com/companies-using-dita/
• Web Content Accessibility Guidelines and check
lists https://www.w3.org/TR/WCAG20/#content-
structure-separation
• DITA 1.3 specifications available free online at
http://docs.oasis-open.org/dita/dita/v1.3/dita-v1.3-
part3-all-inclusive.html
• DCMI Dublin Core specifications
http://dublincore.org/documents/dces/#NISOZ3985

44. Resources
• Subject Classification with DITA markup for Agricultural Learning
Resource. A case example in Agroforestry, in Metadata and Semantic
Research (Thomas Zschoke): 5th International Conference, MTSR 2011;
Elena García-Barriocanal, Zeynel Cebeci, Aydin Öztürk, Mehmet C. Okur
• Tekom: March 2011, Tekom Can you explain that again? DITA for
Beginners by Dr Tony Self
• Definitions from The Language of Technical Communication, Ray Gallon et
al. ISBN 978-1-937434-48-9 XML Press
• What is the Job of the Web Content Professional? Gerry McGovern
http://www.cmswire.com/content-strategy/what-is-the-job-of-the-web-
content-professional/
• Turning the tables with DITA 1.4 http://www.ixiasoft.com/en/news-and-
events/blog/2015/turning-tables-dita-13/
• Gerry McGovern at UXI | Flickr - Photo Sharing!
• Tony Self at WritersUA 2009 Day 1 | ffeathers