STC Austin: Best practices when migrating to DITA

Bernard Aschwanden
www.publishingsmarter.com
bernard@publishingsmarter.com
DITA Conversion Best Practices
13:51
1
@publishsmarter

Overall Objectives
13:51@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

Housekeeping and note taking
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…

About your speaker
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

Standard disclaimer
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)

The initial goodies
@publishsmarter 13:51
6
Topic-based writing

Topic-based single sourcing is more efficient
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

If you single source
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

Basic sample
9

Defining topic-based writing
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)

Reasons topic-based is a good idea
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

The linear approach to content
 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

The modular (topic-based) approach to
content
 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

Benefits to writers and users
 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

It makes content better
15
Structure (and XML)

XML supports structured writing
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

What does it look like?
17
 Looks a lot like HTML (or it can)
 This sample ain’t perfect; just basic ideas.
It’s a aragraph, and has some talic content in it.
The talic content ends, then the 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
Part Function

19
Part Function

20
Part Function

Human usable XML might look more like this
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>
For safety, admins can override preferences.You can
override any personal preferences.</context>
<steps>
<step><cmd>Select <uicontrol>Lighting Configuration</uicontrol>.</cmd></step>
<step><cmd>Tap <uicontrol>Layout</uicontrol>.</cmd>
<info audience="Administrator">
To set global levels, tap <uicontrol>Override all Layouts</uicontrol>.
</info>
</step>
<step>
<cmd>Tap the appropriate light level or configuration.</cmd>
</step>
</steps>
</taskbody>
</task>

Reading it can be pretty simple (ignore code)
22
<taskbody>
<context><indexterm audience="EndUser">lighting</indexterm>
<steps>
</info>
</step>
<step>
</step>
</steps>
</taskbody>
</task>

Structure has some human-friendly feel to it
23
<taskbody>
<steps>
</info>
</step>
<step>
</step>
</steps>
</taskbody>
</task>

You can even understand the attributes
24
<taskbody>
<steps>
</info>
</step>
<step>
</step>
</steps>
</taskbody>
</task>

Remember that XML provides a division
25
Format
Content

With XML you spend your time wisely
26

There ARE better ways to write,
so take advantage of them!
27
New technologies

Notepad. You can edit with Notepad. Woo.
Hoo.
28

Code view if you want/need it
29

Code view is only one option
30

Across multiple tools
31

Mainstream tools offer a lot of support
32

All the code is still there...
33

You can choose to show JUST the EndUser
34

Show and hide based on attributes and values
35

Or choose just Administrator content
36

Display audience specific content
37

Net benefit of two topics, one source
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!

It is not output restrictive

Converted content can be on tablets

Or on phones; it’s device independent

High level ideas on the day-to-day
writing of content
42
How to think about DITA

DITA in a single slide
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

Identify topic types
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

DITA begins with thinking of tasks
45
 The task identifies the
best practice to follow
to achieve a goal
 Step-by-step
 Minimal other
information

If needed, concepts support tasks
46
 The concept
introduces the ideas
 Answers the
questions of “what is”
or “why would I” that
people have

For technical info, references help
47
 Quick access to facts
 Usually a lookup for
people who know the
concept, understand
the task, but need the
quick technical specs

Maps
 Create a relationship
between topics
 Used for navigation,
publishing and more
48

When topics and maps come together
 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

Best practices
While they are BEST practices,
there is a formal approach to them in DITA
50
Things you can do to start

Quick steps to ID what you actually have
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)

Tasks are core in DITA
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

Best practices (both DITA and minimalism)
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

Rework a source quickly
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
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.

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

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.

Add linked pictures (Task)
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.

Reasons to use graphics (Concept)
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.

Supported formats (Reference)
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

Work with graphics (Topic)
61
Microsoft Word, Excel, and PowerPoint
allow you to insert a graphic.

Pulling those topics into a map and
publishing to multiple outputs...
62
Bring it home...

In Serna
63
 Document > New > DITA 1.1 > Topic
 View > Show Markup

In XMetaL
64
 File > New > DITA Topic > Reference
 Add content, use Table > Insert Rows or Columns

In Oxygen
65
 File > New...
 Create a concept, populate it

In FrameMaker
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

In FrameMaker
67

If you build a map, you can also publish it all
68

Summing up the discussion,
and options to continue it.
69
Conclusion and contact

Overall Objectives
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

Follow up contact information
71
905 833 8448 (Eastern Time)
bernard@publishingsmarter.com
www.linkedin.com/in/bernardaschwanden
@publishsmarter
www.publishingsmarter.com

STC Austin: Best practices when migrating to DITA

Recommended

More Related Content

Viewers also liked (7)

Similar to STC Austin: Best practices when migrating to DITA (20)

More from Publishing Smarter (20)

Recently uploaded (20)

STC Austin: Best practices when migrating to DITA