The Three Core Topic Types

The Three Core Topic Types:

Concept, Task, Reference

© Marcia (Riefer Poulsen) Johnston [email protected]

To view in PowerPoint, press the F5 key(or in the menu bar go to Slide Show > View Show),

and click through the slides.

© 2006 Marcia Johnston, [email protected] 3

Thanks

I’m grateful for feedback on this presentation from

STC’s single sourcing & online SIGs STC’s Rochester & Central New York

chapters Tech Comm colleagues at Welch Allyn, Inc.


Assumptions I’m making about you

Experienced tech communicator Think in terms of

information chunks Don’t (yet) think in terms of these

three topic types — or want to refine your topic-writing skills


About me

My experience:

Print = 20+ years Web = some Online Help = some

My interest:

Universal principles of topic-based writing


Why am I sharing what I’ve learned?

Information typing has improved my writing.

It might help yours too.


What we’ll cover What’s a topic? Why write in topics? What tools do we need to create topics? What are these 3 core topic types? Why 3, and why are they core types? Why organize topics by info type? What elements make up topics? What might each topic type look like? What’s the process for topic-based writing? What makes a well-formed topic?


At the end, you’ll make this over.

Isn’t this already in chunks?


What’s a topic?

Information chunk that answers one question

(How do I…? What is...? etc.) has a heading can stand alone —

makes sense in any context

Hey, this slide is an example of a topic.


How does a topic stand alone?

Art borrowed from an ArcSoft PhotoMontage ad

Topics = building blocks

Make sense on their own Can be assembled different ways Avoid transitions at beg. or end (“As you’ve just seen,” etc.)

Do We Really Need All that Glue?JoAnn Hackos on transitional text in topicshttp://dita.xml.org/node/1410

http://dita.xml.org/node/1410


Why write in topics?

Topic-based writing fits the way people seek technical info supports task-centric (vs. product-

centric) documentation supports multiwriter collaboration enables information reuse (single

sourcing) streamlines translation


You don’t need these.

DITA or DocBook, DTDs or schemas XML, HTML, or any other ML Structured FrameMaker A content-management system A particular tool or standard A particular output type (print, Web, Help)


You can create topics with any tool.

“Modular writing is a cognitive process.”

Kurt Ament, Single Sourcing: Building Modular Documentation

Aka topic-based writing


What are the core topic types?

Tells how to do something.Usually includes numbered steps.Task

Concept

Reference Gives details of interest to certain readers, often in look-up lists or tables.

Describes something.


Why three types(at least as a starting point)?

The concept-task-reference triptych has been in use for years, although not embraced by everyone.

The growing use of DITA, which offers these three types “out of the box,” reinforces the consensus.

For more:http://stc-on.org/online/topics/content-management/2006/08/19/topic-types/

http://stc-on.org/online/topics/content-management/2006/08/19/topic-types/

http://stc-on.org/online/topics/content-management/2006/08/19/topic-types/


Why call them core types?

Could say core types, super-types, archetypes, or ur types. These types are universally relevant and customizable.

In DITA, you customize via specialization and inheritance.


What is DITA?

DITA = Darwin Information Typing Architecture

Topic-based XML framework for authoring, managing, publishing technical documentation.

Illustration reprinted with permission from artist, Rick Geary (www.rickgeary.com).

Information typing is DITA’s middle name.


Why structure topics by info type?

So readers instantly know a topic’s purpose:

to help them understand something

to help them do something to provide supporting details

Task

Concep

t Reference


True or False?

“Online information should be presented in screen-sized chunks. People don’t like to scroll down.”

“Hardcopy info is linear, online info is nonlinear.”

Let’s look at each of these fallacies.


This topic is longer becausy of all the steps required to This topic is longer becaush of all the steps required to This topic is longer becausm of all the steps required to

Fallacy:People don’t like to scroll down.

How long should a topic be?Long enough to address the question (How do I…? What is...? etc.).

About WidgetsThis paragraph is all it takes to describe the widget. So, this topic is short.

Topic 1

This topic is longer because of all the steps required to This topic is longer becausc of all the steps required to This topic is longer becaust of all the steps required to

Installing a WidgetThis topic is longer because of all the steps required.1. Do this.2. Do that.

Topic 2


Fallacy:Hardcopy is linear, online is nonlinear.What’s the reality?

In any medium, people sometimes read technical info sequentially and sometimes jump around.

Can’t assume sequential reading in a chapter.

Write for sequential reading in a topic.Topic C Topic X

Topic M

Chap 5 Chap 8

Chap 2


What elements make up topics?

From Introduction to DITA: A User Guide to the Darwin Information Typing Architecture

Elements

Topics

Mini building blocks

Depends on your needs. Here’s one example:


Concept topic — example 1

From The Internet for Dummies, 2nd edition

Elements

Topic


Concept topics — example 2

Can be read in any order.

From Boys’ Life, July 2006

Topic

Topic

Topic

Topic

Topic

Topic

Topic


Task topic — example 1

Elements

Topic

From Polaris® PowerPAC online help


Task topic — example 2Setting Categories

ElementsTopic

From FranklinCovey® planning software online help


Reference topic — example 1

Elements

Topic

From The Internet for Dummies, 2nd editionSidebar adjacent to other topics


Reference topic — example 2

Table tucked away in an appendix

Topic Elements


Okay. I get it. How do I do it?1. Identify the task topics needed — based on user

goals, not user interface. (“Resetting the Trip Timer” vs. “DST Mode”)

2. Identify the concept and reference topics needed to support those tasks. (“About the Trip Timer” or “Specifications”)

3. Create, assemble, and publish the topics.

(≈ TOCs, playlists)

I. Topic areaa. Concept topic b. Task topic

II. Topic area

Might look like an old-fashioned outline.


What makes a well-formed topic?

The rest of presentation addresses this question.

My focus: Common characteristics of all topic types.

Beyond my focus: Specifics on well-formed procedures, descriptions, tables, etc. (widely documented).


4 characteristics of well-formed topics

1. They use heading syntax to communicate info type.

2. They avoid significant mixing of info types.3. They serve as a hub, pointing to related topics

(if appropriate).4. They focus on one user question.

Let’s look at each of these.


Well-formed topic — characteristic 1

A well-formed topic uses heading syntax to communicate info type.


Heading syntax — examplesConcept headings1st word = noun, About, question word

Task headings 1st word = gerund, infinitive, imperative, How To, question word

Reference headings 1st word = noun,question word

Setting Up the XYZ To Set Up the XYZSet Up the XYZHow To Set Up the XYZ How Do I Set Up the XYZ?

XYZ or About XYZWhat Is XYZ?

SpecificationsDo You Need a Number to Get a Name?


For more on verb forms in topic titles

See STC’s Hyperviews Online:

http://stc-on.org/online/topics/content-management/2006/08/15/topic-titles-what-verb-form/





A well-formed topic avoids significant mixing of info types (beyond a few sentences).

Concept with procedure embedded Task with lengthy background embedded Reference table with concepts embedded


Mixed info types — example

This descriptive interruption goes on for another page before wereach step 6!

Concept info embedded in task.

Might want to keep bits of it here.



A well-formed topic serves as a “hub.”

Term used by JoAnn Hackos, quoting Eric Freese, in Content Management for Dynamic Web Delivery


How does a topic serve as a hub?

It’s like a gate at an airport.

It becomes the center of your field of vision when you land there.

It directs you to where you want to go next.

It doesn’t have to convey the layout of the whole airport.

How do we get from here to Gate D25?

Hub


Topics as hubs — example

Task ABC1. Do this.2. Do that.Related InformationConcept PQRReference XYZ

Concept PQRThis explanation tells all about PQR.Related InformationTask ABCReference XYZ

Reference XYZItem DescriptionBlah Blah blah blahBlah Blah blah blah

Related InformationTask ABC Concept PQR

HubHub

Hub

Kurt Ament calls such cross-references “cognitive bridges.” Keep “Related Info” lists short and highly relevant.


Another way to talk about hubs

“To help users navigate modular content, you link standalone content modules with cognitive bridges, or cross-references . . . . When separating different levels of information into distinct content modules, [you] physically separate modules that are thematically related. To make the relationships between the related modules explicit, you add cross-references that link the modules.”Kurt Ament, Single Sourcing: Building Modular Documentation



A well-formed topic answers one user question.

As fully as users need Only as fully as users need

Minimalism


Let’s try some makeovers.

Following are two before and after examples.

I did not make these up.


Makeover #1 — beforeHow well-formed isthis topic?1. Does it use heading

syntax to communicate info type?

2. Does it avoid significant mixing of info types?

3. Does it serve as a hub — point to related topics?

4. Does it answer one user question (only as fully as needed)?


Makeover #1 — after

If a lead-in grows, you might spin it off into its own concept topic.


Makeover #2 — before


Makeover #2 — after


Ideal: Topics that stand alone ANDread well in “browse sequence”

You can jump to these topics in any order

AND

scroll from one to the next.


Your challenge: information modeling

Create an information model* for your context.

What topic types best serve our customers? What elements will those topics typically contain? What syntax patterns will our headings follow? How else can we standardize for more

consistent content structure?

* term used by JoAnn Hackos and others


Child’s play?

Topic-based writing is not always easy to do.But the result is the easiest for people to use.


Books that discuss topic-based writing

Developing Quality Technical Information: A Handbook for Writers and Editors, 2nd ed., IBM Press, Prentice Hall PTR, 2004.

Standards for Online Communication, JoAnn Hackos & Dawn Stevens, John Wiley & Sons, 1997.

Single Sourcing: Building Modular Documentation, Kurt Ament, William Andrew Publishing, 2003.

Introduction to DITA: A User Guide to the Darwin Information Typing Architecture, Jennifer Linton & Kylene Bruski, Comtech Services, 2006 (written using DITA).

Content Management for Dynamic Web Delivery, JoAnn Hackos, Wiley Computer Publishing, 2001.


Recommended newsletter

Best Practices, a Publication of the Center for Information-Development Management

(JoAnn Hackos, publisher and CIDM director)

www.infomanagementcenter.com/newsletter.htm

http://www.infomanagementcenter.com/newsletter.htm

http://www.infomanagementcenter.com/newsletter.htm


Excellent article

10 DITA Lessons Learned From Tech Writers in the Trenches

“The main difficulty writers had was to make the switch to writing topic based material. ”

http://thecontentwrangler.com/article/10_dita_lessons_learned/




Excellent free recorded webinars on DITA

https://xmetalevents.webex.com > View All Recorded Events

Sponsored by XMetaL. List captured June 22, 2006.

https://xmetalevents.webex.com/

Documents

The Three Core Topic Types