The document provides an overview of a presentation on DITA conversion best practices. The presentation will cover the advantages of authoring in a topic-based environment, how to assess your current situation and plan for the future, and how to execute that plan. Attendees will understand topic-based writing and DITA, best practices for organizing content, and how DITA relates to their needs. The speaker will also discuss housekeeping for the presentation and provide information about themselves.
2. Overall Objectives
23:56@publishsmarter
2
Advantages to authoring in a topic based environment
More efficient
Structure helps produce better content
Takes advantage of new technologies for delivering content
I plan to share the best way to
Assess your current situation
Plan for your future and
Execute to the plan
After the presentation, you will:
Understand what topic–based writing is and its advantages
Follow best–practices for organizing new material into topic–based
content
Understand the place of XML and DITA and how they may relate to
your needs
3. Housekeeping and note taking
23:56@publishsmarter
3
Not all slides or topics are
equally weighted
Use some, discard others
Slides speed varies
(reference)
Questions? Ask along the
way!
I’d love to claim errors/typos
is on purpose… they isn’t,
ain’t, and weren’t never;
however, I’ll fix ‘em as I
can…
4. About your speaker
23:56@publishsmarter
4
Publishing Smarter:
President
Content strategist,
publishing technologies
expert, author, and geek-
enough
Certified Technical Trainer
DITA
Content management
Topic-based writing
Society for Technical
Communication
Vice President
STC Associate Fellow
5. Standard disclaimer
23:56@publishsmarter
5
In the interest of brevity I
will make some blanket
statements to keep it
simple
It’s not all 100% “the
truth”, but I’ll stay close
Purists may complain
And they are wrong!
(except when they are
right)
7. Topic-based single sourcing is more efficient
23:56@publishsmarter
7
Use the same content in more than one location
This could be across:
Output types (online help, user’s guide)
Perhaps graphics are excluded, or specific topics not
needed/added
Projects (new version re-uses content from last version)
Products (t40 and t41 are similar products, 90% the same)
Departments (Marketing re-uses Doc’s content)
User types (novice and advanced users)
Operating systems (Windows, Mac, Unix, Android)
Many instances of the same topics, unique order
8. If you single source
23:56@publishsmarter
8
Try to share topics in their entirety
Create content that is free of ‘specifics’
Product names
Screen shots
Other identifying content
If you need specifics, can you conditionalize ‘chunks’
Entire sections
Paragraphs
Images
10. Defining topic-based writing
23:56@publishsmarter
10
A way to create content from standalone topics
which are:
Smallest possible unit of information that makes sense on its
own (no absolute dependencies)
Reusable as a standalone unit of information
Based on information type (e.g., concept, reference, task)
Can be assembled to create help, HTML, PDF, etc
Linked and referenced to build relationships
Not applicable to all doc types though
Marketing, legal, regulatory may be far more focused
However, ideas can still apply (targeted writing)
11. Reasons topic-based is a good idea
23:56@publishsmarter
11
An alternative to linear writing
Traditional book model
Writing in chapters
Order matters (before/after)
A method of focusing on your users’ needs
A way to chunk information based on types
Fundamentally, a way of organizing your content into
easily digestible pieces
12. The linear approach to content
23:56@publishsmarter
Linear means:
Content is related to
previous and following
content
It's not easy to re-order
If you do NOT know the
order, then the context
can be lost very quickly
12
13. The modular (topic-based) approach to
content
23:56@publishsmarter
Modular means:
Pieces of information
must make sense without
context
Pieces of information can
be moved around
Context may or may not
bring extra meaning to
individual pieces
People jump in where
and when they need
content
13
14. Benefits to writers and users
23:56@publishsmarter
To the writer
Team collaboration
Easier review cycle
Create it faster
Solid time management
Less time formatting
Share content
Shorter content
Fewer opportunities for
mistakes
To the user
Read what you want
Read in the order you
want
Common layout makes it
fast to scan and find
content (beyond search)
14
15. It makes content better
@publishsmarter 23:56
15
Structure (and XML)
16. XML supports structured writing
23:56@publishsmarter
16
Structure implies a set
of defined rules (law,
math, engineering,
grammar)
Writing implies the
creation of content
Structured content
consistently follows rules
A good foundation
results in a happy home
17. What does it look like?
23:56@publishsmarter
17
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
18. What does it look like?
23:56@publishsmarter
18
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
19. What does it look like?
23:56@publishsmarter
19
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
20. What does it look like?
23:56@publishsmarter
20
Looks a lot like HTML (or it can)
<p>This sample <i>ain’t</i> perfect; just basic ideas.</p>
It’s a <p>aragraph, and has some <i>talic content in it.
The </i>talic content ends, then the </p>aragraph ends.
<img src=“logo.gif” height=“100” width=“50” />
Let’s dissect an element
Part Function
img Name of the element
src Name of an attribute
logo.gif Value of the attribute
21. Human usable XML might look more like this
23:56@publishsmarter
21
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser“>
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
22. Reading it can be pretty simple (ignore code)
23:56@publishsmarter
22
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser">
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
23. Structure has some human-friendly feel to it
23:56@publishsmarter
23
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser">
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
24. You can even understand the attributes
23:56@publishsmarter
24
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "technicalContent/dtd/task.dtd" []>
<task id="id_t_lighting_lvl">
<title>Adjust lighting levels</title>
<shortdesc>Room or seat brightness can be individually configured.</shortdesc>
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm><p audience="EndUser">
For safety, admins can override preferences.</p><p audience="Administrator">You can
override any personal preferences.</p></context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
<p>To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.</p>
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>
25. Remember that XML provides a division
23:56@publishsmarter
25
Format
Content
26. With XML you spend your time wisely
23:56@publishsmarter
26
27. There ARE better ways to write,
so take advantage of them!
@publishsmarter 23:56
27
New technologies
28. Notepad. You can edit with Notepad. Woo.
Hoo.
23:56@publishsmarter
28
29. Code view if you want/need it
23:56@publishsmarter
29
30. Code view is only one option
23:56@publishsmarter
30
38. Net benefit of two topics, one source
23:56@publishsmarter
38
Less editing
Fewer edits
Less review time
Quicker approvals
Fewer overall words to manage
And, as the content is created, you can publish to
any output that you need!
39. It is not output restrictive
23:56@publishsmarter
42. High level ideas on the day-to-day
writing of content
@publishsmarter 23:56
42
How to think about DITA
43. DITA in a single slide
23:56@publishsmarter
43
D is for Darwin
Evolves and adapts, over time DITA is adding
new topic types, elements, as well as tools
and best practices
Specializes, when it can’t meet your needs,
you can customize
IT is for Information Typing
Info is organized/classified into
task/concept/reference
A is for Architecture
A formal set of rules
Planned and developed
DITA is primarily about
Topics and Maps (and planning)
Connect People
and Content
44. Identify topic types
23:56@publishsmarter
44
topic: A meaningful, stand–alone unit of
information, eg. Work with images
three primary topic types matter
task: Procedural details such as step-by-step
instructions. eg. Import images, Resize images
concept: Background info that users need to
know. eg. Reasons to use images
reference: Quick access to tech info, or facts.
eg. Supported image formats, Raster versus
vector
map: Contains info about relationships
between topics, appropriate metadata,
and optional linking and navigation
TOPIC
REFERENCECONCEPT
TASK
45. DITA begins with thinking of tasks
23:56@publishsmarter
45
The task identifies the
best practice to follow
to achieve a goal
Step-by-step
Minimal other
information
46. If needed, concepts support tasks
23:56@publishsmarter
46
The concept
introduces the ideas
Answers the
questions of “what is”
or “why would I” that
people have
47. For technical info, references help
23:56@publishsmarter
47
Quick access to facts
Usually a lookup for
people who know the
concept, understand
the task, but need the
quick technical specs
49. When topics and maps come together
23:56@publishsmarter
A resulting hierarchy of
information exists
Materials are easier to
read, quicker to scan
When published, delivers
minimalist, clear, and
easy to use content
The result of using DITA
is more than just clear
content
Navigation between
topics automatic
Further navigation can
also be developed
49
TOPIC
REFERENCECONCEPTTASK
50. Best practices
While they are BEST practices,
there is a formal approach to them in DITA
@publishsmarter 23:56
50
Things you can do to start
51. Quick steps to ID what you actually have
23:56@publishsmarter
51
Review your table of contents
Build a TOC with steps, figures, tables in it
Review it again
Start to quickly ID
See if you can guess what is a task/concept/reference
Compare your TOC info with the body of the content
If there isn’t a match that is a clear T, C, R, then rework (ideas
follow)
52. Tasks are core in DITA
23:56@publishsmarter
52
Remember that tasks are a core part of DITA
Odds are people are doing things when they
discover a need to look up docs
Tasks are the most likely place users turn
Make sure you explain the “how to” and support that
with other information
53. Best practices (both DITA and minimalism)
23:56@publishsmarter
53
Stick to one way to tell people how to do it
Don’t mix icons, shortcuts, and menus in a task (I like Select
File > Open. Menus rarely are customized/hidden unlike
keyboard commands or toolbars) BTW: Good design is also
good minimalism!
Avoid features (that’s concept)
<cmd> is 1 sentence
If needed, 1 level of substeps
Avoid stem sentence lead-ins
Best: Clear title, familiar patterns
Less to translate and manage
54. Rework a source quickly
23:56@publishsmarter
54
Take the next slide and mark it up
Use (color, bold, italic, whatever…) to ID topic type
Task, concept, or reference identifiers
Rework into core task/concept/reference
This is an online exercise, and I’ll use the chat, but
you can do this on your own with your content too!
Later: Find a good sample of your own content,
and try this for yourself
55. 23:56@publishsmarter
55
Microsoft Word, Excel, and PowerPoint allow you to
insert a graphic. Graphical images add value to
documents by making it easier to see any type of
idea represented as a picture. They also break up
content rich materials. Many formats (including
common ones like jpg, gif, bmp, or even pdf) are
supported in most of the tools. To insert an image in
any one of these applications you can use the Insert
menu and choose Picture after you select a
location. Then choose and import an image in one
of the supported formats. Make sure you manage
graphics well! You may want one folder for all your
images instead of looking everywhere for them.
56. 23:56@publishsmarter
56Microsoft Word, Excel, and PowerPoint allow you to
insert a graphic. Graphical images add value to
documents by making it easier to see any type of idea
represented as a picture. They also break up content rich
materials. Many formats (including common ones like
jpg, gif, bmp, or even pdf) are supported in most of the
tools. To insert an image in any one of these
applications you can use the Insert menu and
choose Picture after you select a location. Then
choose and import an image in one of the supported
formats. Make sure you manage graphics well! You may
want one folder for all your images instead of looking
everywhere for them.
Task Concept Reference Undecided
57. 23:56@publishsmarter
57Microsoft Word, Excel, and PowerPoint allow you to
insert a graphic.
Task: To insert an image in any one of these
applications you can use the Insert menu and
choose Picture after you select a location. Then
choose and import an image in one of the supported
formats.
Concept: Graphical images add value to documents by
making it easier to see any type of idea represented as a
picture. They also break up content rich materials. Make
sure you manage graphics well! You may want one
folder for all your images instead of looking everywhere
for them.
Reference: Many formats (including common ones like
jpg, gif, bmp, or even pdf) are supported in most of the
tools.
58. Add linked pictures (Task)
23:56@publishsmarter
58
Linked graphics ensure that when a
source changes, your documents remain
current.
Prerequisite: Use specific tools to create
images first; then add images as needed.
1. Choose a location for an image
2. Select Insert > Picture
3. Choose an image type
4. Double click the image to import
When done: Position or size the image.
59. Reasons to use graphics (Concept)
23:56@publishsmarter
59
Graphics add value to documents by
making it easier to see ideas
represented visually. They also break up
text rich materials.
TIP: Manage graphics well! You may
want one image folder with all images
instead of looking everywhere for them.
60. Supported formats (Reference)
23:56@publishsmarter
60
Multiple image formats can be imported.
Type Value Description
Raster image:
Joint
Photographic
Experts Group
jpg or
jpeg
Often used online,
good for photos or
gradient based
images, high color
definition support
Raster image:
Graphics
Interchange
Format
gif Often used online,
good for basic image,
up to 256 color
support, includes
transparency
61. Work with graphics (Topic)
23:56@publishsmarter
61
Microsoft Word, Excel, and PowerPoint
allow you to insert a graphic.
62. Pulling those topics into a map and
publishing to multiple outputs...
@publishsmarter 23:56
62
Bring it home...
66. In FrameMaker
23:56@publishsmarter
66
DITA > New DITA File > New <task> and View >
Element Boundaries as Tags, the populate task (if
desired, also show Element > Catalog and Structure
Tools > Structure View
Tutorials: www.publishingsmarter.com
68. If you build a map, you can also publish it all
23:56@publishsmarter
68
69. Summing up the discussion,
and options to continue it.
@publishsmarter 23:56
69
Conclusion and contact
70. Overall Objectives
23:56@publishsmarter
70
Advantages to authoring in a topic based environment
More efficient
Structure helps produce better content
Takes advantage of new technologies for delivering content
I plan to share the best way to
Assess your current situation
Plan for your future and
Execute to the plan
After the presentation, you will:
Understand what topic–based writing is and its advantages
Follow best–practices for organizing new material into topic–based
content
Understand the place of XML and DITA and how they may relate to
your needs
71. Follow up contact information
23:56@publishsmarter
71
905 833 8448 (Eastern Time)
bernard@publishingsmarter.com
www.linkedin.com/in/bernardaschwanden
@publishsmarter
www.publishingsmarter.com