06:23

Bernard Aschwanden

www.publishingsmarter.combernard@publishingsmarter.com

VIDEO of this presentation is also availablehttps://www.youtube.com/watch?v=yE9cjNxiqMs

Topic-Based Writing:From Idea to Output

1

@publishsmarter

06:23

What to expect

@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

06:23@publishsmarter

3

Standard disclaimer

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

06:23

But what if it’s too fast?

@publishsmarter

4

No worries as it’s all recordedSlides 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

06:23

What it is, where it matters,how to get there

@publishsmarter

5

Topic-based writing

06:23

6

What it is

@publishsmarter

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

06:23

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

@publishsmarter

Defining modular (topic-based system)

06:23

8

Thinking in topics

@publishsmarter

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

06:23

Benefits of topic-based content for users

@publishsmarter

9

Read what you wantRead in the order you wantCommon layout makes it fast to scan and find

content (beyond search)Right information, right format, right timeInformation 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

06:23

Sometimes you can say more by not saying anything at al l

@publishsmarter

10

Text substitution

06:23

11

Tables

@publishsmarter

Best used in reference materialsShort, concise comparisonsIn 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

06:23

Sample keyboard shortcuts

@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)

06:23

Value of an image

@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

06:23

Complex image with a callout table

@publishsmarter

14

# Name # NameA Revolving

nosepieceF Arm

B Objective G StageC Stage clips H Coarse adjustment

knobD Diaphragm I Fine adjustment

knobE Light

sourceJ Base

AB

CDE

F

GHI

J

06:23

Orient users in large images

@publishsmarter

15

Step 2: Use the dipstick to check lubricant levels

06:23

Organize information

@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 thingMammal Avg

length/heightHuman being 5’7”Beluga whale 18’Blue whale 98’

6’ / 2m

< 6’

98’

18’

06:23

Based on DITA because, well . . .

@publishsmarter

17

Let’s get into topics

06:23

18

DITA should matter to you

@publishsmarter

A growing standard with vendor supportMore companies looking for DITA skillsNot just structured writing; best practices:

Planning content Organizing information Developing relationships Using automation where it makes sense

06:23

19

Darwin Information Typing ArchitectureDITA is about Topic, Maps, SpecializationsSome common topic types include

concept reference task glossary bookmap and map

@publishsmarter

DITA in a single slide

DITA Information TypesTopic–Concept–Task–Reference

06:23

Types of topics

@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

06:23

Start with tasks

@publishsmarter

21

Odds are people are doing things when they discover a need to look up docs

Tasks are the most likely place users turnAn answer to how that tells the user just what

to do and the order in which to do itStep-by-step instructions that enables a user

to actually do something

06:23

Support them with concepts and references

@publishsmarter

22

Concepts explain “what is” or “why would I” info

References are more “tech specs”

06:23

For example, if talking about saving files…

@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

@publishsmarter 06:23

24

Good question, let’s go play

What about “hands-on” stuff?

06:23

From the outline

@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

06:23

Working the sample documents

@publishsmarter

26

Several tools, using DITAOxygen to create contentXML to edit contentFrameMaker to publish contentAnd back again…

06:23

Publish the output

@publishsmarter

27

All the tools allow you to publish contentAnd more are out there

@publishsmarter 06:23

28

Summing up the discussion,and options to continue it.

Conclusion and contact

06:23

Follow up contact information

@publishsmarter

29

905 833 8448 (Eastern Time)

bernard@publishingsmarter.com

www.linkedin.com/in/bernardaschwanden

@publishsmarter or @aschwanden4stc

www.publishingsmarter.com