Text-rich, illustration-heavy, table-filled, overly-hyphenated manuals and docs sit on the shelf and never get read. Today, we read information in the format we want, on whatever device we want, and with just enough information to support what we need to do. Learn more about topic-based writing, what it is and what it can do for your approach to documentation. Any device, any time, any format.

1. Bernard Aschwanden
www.publishingsmarter.com
bernard@publishingsmarter.com
VIDEO of this presentation is also available
https://www.youtube.com/watch?v=yE9cjNxiqMs
Topic-Based Writing:
From Idea to Output
17:44
1
@publishsmarter

2. What to expect
17:44@publishsmarter
 Text-rich, illustration-heavy,
table-filled, overly-hyphenated
manuals and docs sit on the
shelf and never get read
 Today, we read information
in the format we want, on
whatever device we want, and
with just enough information
to support what we need to do
 Learn more about topic-based
writing, what it is and what it
can do for your approach to
documentation
 Any device, any time,
any format
 Smaller chunks of
information, topic types,
reusable, assembled as
needed, delivered in any
format
 Explore the idea of topic-
based writing, single-sourcing
materials, and replacing some
text with audience friendly
information
 We'll create a sample
document set, update
materials in many software
tools, and deliver PDF,
XHTML, web-friendly, multi-
device, platform
independent information
2

3. Standard disclaimer
17:44@publishsmarter
 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)
 In the interest of time and
content I’ll go quickly
3

4. But what if it’s too fast?
17:44@publishsmarter
4
 No worries as it’s all recorded
 Slides are online as well at:
 http://www.slideshare.net/PublishingSmarter/topic-based-
writing-from-idea-to-output
 And the video to go with this is online too!
 https://www.youtube.com/watch?v=yE9cjNxiqMs

5. What it is, where it matters,
how to get there
@publishsmarter 17:44
5
Topic-based writing

6. What it is
17:44@publishsmarter
6
 A way to create content from standalone topics each
of which is:
 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 (concept, reference, task)
 Can be assembled to create help, HTML, PDF, etc
 Linked and referenced to build relationships

7.  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
17:44
7
@publishsmarter

8. Thinking in topics
17:44@publishsmarter
8
 In the past
 Content flowed from first, to second, to third
 Dependencies created to ‘before’ and ‘after’ content
 Difficult to reuse or reorganize with ease
 With topic-based writing
 Content becomes discrete, stand-alone unit of info
 No concept of ‘before’ or ‘after’ but rather ‘related’
 Context of use may modify the message

9. Benefits of topic-based content for users
17:44@publishsmarter
9
 Read what you want
 Read in the order you want
 Common layout makes it fast to scan and find
content (beyond search)
 Right information, right format, right time
 Information is in topic types, each with a purpose
 Task: How to complete a goal
 Concept: Why a goal is worth achieving, or what it is
 Reference: Quick lookup or guide to technical specs

10. Sometimes you can say more by not
saying anything at all
@publishsmarter 17:44
10
Text substitution

11. Tables
17:44@publishsmarter
11
 Best used in reference materials
 Short, concise comparisons
 In tasks, avoid If… Then… approach
 Generally these are tasks or broken out
 Consider substeps
 Some may be reference info instead
 If documenting issues, fix the UI
 In electronic docs these may also be able to sort
content based on user requests

12. Sample keyboard shortcuts
17:44@publishsmarter
12
Function Modifier Key Icon Notes
Cut Ctrl x Places selected content on the clipboard.
Copy Ctrl c Places selected content on the clipboard.
Paste Ctrl v Places clipboard content at the insertion point.
Font edit Ctrl+Shift f Opens the font dialog to edit text appearance.
Function Modifier Key Icon Notes
Copy Ctrl c Places selected content on the clipboard.
Font edit Ctrl+Shift f Opens the font dialog to edit text appearance.
Paste Ctrl v Places clipboard content at the insertion point.
Cut Ctrl x Places selected content on the clipboard.
Sort by Key
Default sort as presented (grouped by functions)

13. Value of an image
17:44@publishsmarter
 Rather than text
 The breather is located on
top of the pump and is
usually capped in black.
 Consider this:
 Rather than text
 The valve is located
between the main tank
and the exhaust pipe.
 Consider this:
13

14. Complex image with a callout table
17:44@publishsmarter
14
# Name # Name
A Revolving
nosepiece
F Arm
B Objective G Stage
C Stage clips H Coarse adjustment
knob
D Diaphragm I Fine adjustment knob
E Light source J Base
A
B
C
D
E
F
G
H
I
J

15. Orient users in large images
17:44@publishsmarter
15
Step 2: Use the dipstick to check lubricant levels

16. Organize information
17:44@publishsmarter
16
 A comparison of average size tells you whales are
big:
 US male is 5’9”
 US female is 5’4”
 Beluga whale is 18’ long
 Blue whale is 98’ long
 A table can tell you the same thing
Mammal Avg length/height
Human being 5’7”
Beluga whale 18’
Blue whale 98’
6’ / 2m
< 6’
98’
18’

17. Based on DITA because, well...
@publishsmarter 17:44
17
Let’s get into topics

18. DITA should matter to you
17:44@publishsmarter
18
 A growing standard with vendor support
 More companies looking for DITA skills
 Not just structured writing; best practices:
 Planning content
 Organizing information
 Developing relationships
 Using automation where it makes sense

19.  Darwin Information Typing Architecture
 DITA is about Topic, Maps, Specializations
 Some common topic types include
 concept
 reference
 task
 glossary
 bookmap and map
17:44@publishsmarter
19
DITA in a single slide
DITA Information Types
Topic–Concept–Task–Reference

20. Types of topics
17:44@publishsmarter
20
 Tasks: Start with tasks (Users don’t
want to learn about something unless
they have to)
 What does the user need to do? Identify those
and then write how they do it.
 Concepts: Supporting info for a task
 In many cases, concepts can provide a clear
conceptual model that is lacking in a task. Used
to orient the users.
 References: Quick look up; no
procedures, no conceptual information

21. Start with tasks
17:44@publishsmarter
21
 Odds are people are doing things when they
discover a need to look up docs
 Tasks are the most likely place users turn
 An answer to how that tells the user just what to do
and the order in which to do it
 Step-by-step instructions that enables a user to
actually do something

22. Support them with concepts and references
17:44@publishsmarter
22
 Concepts explain “what is” or “why would I” info
 References are more “tech specs”

23. For example, if talking about saving files…
17:44@publishsmarter
23
 Task
 Save a file
 Save a file with a new name, or to another location
 Concept
 When you save files, this is what happens
 Reasons to save files
 References
 File formats

24. Good question, let’s go play
@publishsmarter 17:44
24
What about “hands-on” stuff?

25. From the outline
17:44@publishsmarter
25
 We'll create a sample document set, update
materials in many software tools, and deliver PDF,
XHTML, web-friendly, multi-device, platform
independent information

26. Working the sample documents
17:44@publishsmarter
26
 Several tools, using DITA
 Oxygen to create content
 XML to edit content
 FrameMaker to publish content
 And back again…

27. Publish the output
17:44@publishsmarter
27
 All the tools allow you to publish content
 And more are out there

28. Summing up the discussion,
and options to continue it.
@publishsmarter 17:44
28
Conclusion and contact

29. Follow up contact information
17:44@publishsmarter
29
905 833 8448 (Eastern Time)
bernard@publishingsmarter.com
www.linkedin.com/in/bernardaschwanden
@publishsmarter or @aschwanden4stc
www.publishingsmarter.com