Topic-oriented writing structures information around topics rather than categories. It allows for easier access, scanability, modular writing by multiple authors, and facilitation of content reuse. Topic types include concept, reference, and task. A topic has a title describing its theme, followed by mixed text and images. The process involves determining topic types, writing topical titles, and describing each topic's theme. This approach can be applied to existing material by analyzing content, determining topic types, rewriting titles, and using tables to remove repetition.

1. © 2009 McAfee, Inc.
Creating documentation
using topic-oriented writing
John Sarr, Senior Technical Writer

2. 2
5/18/2016
What is topic-oriented writing?
An information architecture that:
For users
— Allows easier access and scanability of information
— Helps factor out supporting concepts and reference information, where
they can be read if required and ignored if not (easier to digest)
For writers
— Allows for easy and consistent design of new information
— Ensures the right design gets used for a particular type of information
(step procedures in tasks, but not in concept information)
— Eliminates unimportant or redundant information
— Identifies common or reusable material
— Allows for modular writing and facilitates work by several authors on one
project
— Facilitates the creation of indexing/topic maps
— Provides a structure for books, chapters, and chapter sections
— Allows for a mapping of user stories to topics
— Facilitates the move to XML

3. 3
5/18/2016
Where does topic-oriented writing fit in
and how are topics involved?
Where is topic-oriented writing used?
• With DITA.
What is DITA?
• Darwin Information Typing Architecture is an
XML-based set of design principles for creating
"information-typed" modules at a topic level.
• DITA provides a core Document Type Definition
(DTD) and schema, which define a topic.
• DITA uses “specialization” to handle different
topic types for the content, and different delivery
maps for the output, such as a Help set, a pdf,
or a readme document. Specialization provides
a better, more overt, and more manageable
mechanism for managing both the data and the
mechanisms for transforming the data.
• Conceived over several years at IBM and now
being managed by a technical committee at
OASIS.

4. 4
5/18/2016
Where does topic-oriented writing fit in
and how are topics involved?
What is a topic?
• Unit of information that describes a single task, concept,
or reference item.
How is a topic constructed?
• Starts with a title followed by a mix of text and images.
How is a topic used?
• Topics are organized into container sections (chapters,
maps), and they can also nest.

5. 5
5/18/2016
What is the process used for creating
topic-oriented writing?
1. Determine the topic type for a section or “chunk” of
content (sections of information in a chapter,
heading1 or heading2), using one of three types:
concept, reference, task. Topic types determine the
structure of their content.
2. Write a title for the topic that describes the topic’s
theme and not its category. Verify that each topic
makes sense standing on its own.
3. Write a short description that defines the theme of
topic.

6. 6
5/18/2016
Topic Type—Applying information typing
• What is it? The practice of classifying content by topic types. Content
that answers different kinds of questions is categorized as different
topic types.
• This approach is based on extensive research and experience,
including Robert Horn's Information Mapping, Hughes Aircraft's STOP
(Sequential Thematic Organization of Proposals), and DITA.
Suggestion for division into information topics types:
• Three topic types provided by DITA (concept, task, reference). Other
systems, use six to eight topic types, but all could be narrowed down
to this DITA-based triad.
• Keep topic types as separate entities. Do not place task or reference
content in a concept topic.

7. 7
5/18/2016
Topic Type—Comparing info type schemas
Info Mapping
• Procedure: task, tell how to do something
• Process: tell what happens, how it works
• Structure: show what it looks like; diagrams,
screenshots
• Concept: tell what it is, how it works
• Principle: provide guidelines, requirements,
policies
• Fact: provide specifications
• Classification: explains types and categories
Longhorn Help
• Conceptual: the most generic of all the content types
• FAQ: use to create frequently asked question (FAQ)
documents (reference)
• Glossary: (reference)
• Procedural: use to create topics consisting of one or
more sets of numbered steps that show how to perform
a particular task
• Reference: use to create developer reference topics
(coding, reference)
• Reusable content: use to combine multiple documents
by defining blocks of linkable content
• Troubleshooting: (reference)
• Tutorial: use to provide instructions for performing
tasks that exceed the scope of a procedure. Typically, a
tutorial encompasses two or more shorter procedures
DITA (Darwin Information Typing Architecture)
• Concept: An extended definition
(description) of a topic. Typically a concept
contains a title, some text, and maybe an
example or a graphic.
• Task (or procedure, instruction): A number
of steps, describing how to do something.
• Reference: An overview of the constituent
parts (characteristics) of a product, an
organization, or an application. A reference
contains mostly data-oriented (rather than
text-oriented) information. (This combines the
process, principle, structure, and fact of
InfoMapping.)

8. 8
5/18/2016
Topic Type—Why use DITA topic types?
Easy to structure content into one of three types: concept, task, and reference
information.
This division covers the basic topics we are trying to present in our
documentation, which answer these questions:
1. WHAT IS IT? (Topic title suggestion: How X works)
Concept: Narrative of what it is and how it works, accompanied by process graphics.
2. HOW DO YOU DO IT? (Topic title suggestion: *ing (gerund) an element of X)
Task: Specific step procedures on how to do something, accompanied by screen
shots where appropriate.
3. WHAT DO YOU NEED TO DO WITH IT & WHY?
(Topic title suggestion: The y elements of X)
Reference: Everything that is not concept or task. It could be a set of best practices,
requirements, FAQs, or material for appendixes.

9. 9
5/18/2016
Applying topic titles to bring out the theme
of a topic
Category vs. topical
• Each topic needs a title. Topic titles should not describe
the category but the theme of the topic, taking into
consideration the audience and purpose of the topic.
Thus, the major shift is from a categorical arrangement of
information to a “topical” arrangement of information.
What happens with topical titles:
• the purpose of the topic becomes apparent
• the scope of a group of topics is revealed
• the information can be approached from a non-linear
perspective

10. 10
5/18/2016
Seeing how topic titles reveal more
information by describing the theme
This is a category TOC
(Note naming which is relevant only within the
linear context and which describes the category
of content. A four-level deep hierarchy.)
Automatic Detection
Introduction
Automatic Detection Techniques
Introduction
External Radar Phenomena
CNFAR Quantization
Multilevel Thresholds
Adaptive Environment Control
Parallel Channels
Adjustments
Pattern Analysis
This is a topical TOC
(Note topic titles that describe the theme. A two-level
deep hierarchy with more top levels to the hierarchy):
Design Approach for Automatic Detection
Automatic Detection Principles
Techniques For Automatic Target Detection
Considerations Of Radar Environment
Hughes Video Processing Methods
Adaptive Control Methods in Automatic Detection
Statistical Video Quantizer Concept
Ability To Verify CNFAR Threshold With Range
Performance Data On Model Statistical Quantizer
Use Of Parallel Channels For Automatic See-Through
Means Of Combating Friendly Interference
Adjusting False Alarm Rate To Obtain See-Above
Adjusting Detection Criteria For Broken-Up Clutter
Pattern Analysis Methods in Automatic Detection
Preventing False Target Reports By Hit-Pattern Analysis
Automatic Reports With Moving-Window Detection

11. 11
5/18/2016
Advice for writing topic titles
The topic title must characterize and introduce the thematic content and not
merely categorize the content. Topic titles work better if they are constructed
as sentence fragments and rewritten after composition of the content.
Topic containers, the highest level (a book or chapter), can stand as a noun
group: Product X User Guide, as it is not written to. However, for topics,
which are written to, follow these suggestions:
• Always answer the question “What about?” the topic.
— With the chapter heading Basic Concepts ask: What about them?
Change to: Understanding basic concepts or something similar.
• Make topic heading a phrase or sentence fragment of 4-8 words containing:
— Prepositions: Nonsystematic errors => Reduction of nonsystematic
errors
— Infinitives: Ways to simplify antenna design
— Gerunds: Controlling characteristic impedance
• If you can take a position, show attitude with qualitative words:
— Advantages of ….
— Limitations of…
— Pitfalls of …

12. 12
5/18/2016
Definitions in topic-oriented writing
• Topic Container: a high-level division of information; namely, a
chapter/map. Used as a categorical devise to orient the reader to
the topics.
• Topic: basic standalone unit comprising a topic title and topic
content that may be divided into labeled chunks. A topic conforms
to one of three topic types.
• Topic type: a category or information type that determines the type
of information contained in a topic and the way the information is
presented. We are using three topic types: concept, reference,
task.
• Topic title: a title for a topic, usually Heading1, that describes the
theme and not the category of the topic.

13. 13
5/18/2016
How to apply topic-oriented writing
to existing material
Take an existing chapter, analyze it, and change it in the
following manner:
• Look at the content in each section divided by headers
and determine the topic types (Concept, Reference, or
Task). Be sure that there is no mixture of types.
• Rewrite topic titles to describe the theme of the topic.
• Use tables, particularly in task procedures and with
reference data, to remove repetitive information.

14. 14
5/18/2016
Example 1: Redoing a concept topic
Before
Categorical headings
Two or more topics
Diffuse: References to more info
After
Topical heading
Single topic
Concentrated: Self-contained info

15. 15
5/18/2016
Example 2: Redoing a task topic
Before
Mixture of concept and task
Diffuse: option details interrupts flow of procedures
Repetition
After
Task only
Concentrated: option details do not interrupt flow of
procedures
Repetition avoided through the use of a table

16. © 2007 McAfee, Inc.
Short descriptions

17. DITA Short Description Guidelines
•How do short descriptions work?
•Why care about writing good short descriptions?
•Topic types considered
— Concept
— Task
— Reference
17
5/18/2016

18. What is the DITA short description?
• A short description is content that appears in the
<shortdesc> DITA element.
• The <shortdesc> element goes directly after the topic title
element.
• Short descriptions serve the following purposes:
— They are the first paragraph in a topic.
— They appear in popup link text when you hover over a link to that
topic.
— They appear after child-link titles.
— They appear in Internet search results.
18
5/18/2016

19. First paragraph of a topic
19
5/18/2016

20. Link text in hover help
20
5/18/2016

21. Short description text in child links
21
5/18/2016

22. Internet search results from Google
22
5/18/2016

23. What to avoid for a short description
• Don’t repeat the title
— What’s the point of simply repeating the title?
• Don’t use a phrase
— All short descriptions must be full sentences to aid translation.
• Don’t say too much
— Short descriptions should be short. Give only enough information so that
the user knows whether to read on. Also, if possible, give just enough
information so that advanced users can get what they need from the
short description and not need to read more.
• Don’t be self-referential
— Don’t refer to the topic in the short description. Example: “This topic will
describe [or discuss or cover] things and stuff.” Short descriptions should
not be self-referential.
23
5/18/2016

24. What to write for a short description
• Short descriptions should contain 50 words or fewer in
one or two sentences. Try to keep short descriptions to
about 25 words.
24
5/18/2016

25. Concept topic
Concept short descriptions provide:
— Answers to what is this? or why should I care about this?
— Definitions
Bad
“Crawlers”
— This topic is about crawlers, which are programs that search for
information.
Good
“Crawlers”
— Crawlers are programs that search for information on the Web, in
databases, or in other data sources. The information that the
crawlers gather is added to the search engine index.
25
5/18/2016

26. Task topic
Task short descriptions define:
— What the topic helps you accomplish
— The benefits of the task
— The purpose of the task
— Situations when the task is useful or necessary
Bad
“Changing data types”
You can use the ALTER NAME statement to change the data type of a
column.
Good
“Changing data types”
You can change the data type of a column so that your data types are
consistent across tables. Use the ALTER NAME statement to change the
data type of a column.
26
5/18/2016

27. Reference topic
Reference topic short descriptions show:
— What the reference object does
— How the referenced item works
— What the referenced item is used for
Bad
“CatStatsCache log file”
This log file describes the cat statistics cache.
Good
“CatStatsCache log file”
The CatStatsCache log file describes the cache that holds the cat
statistics. You can use the information that is in this log file to find
problems with servers that are in other tiers.
27
5/18/2016

28. Reference topic: What’s new ….
• A What's new topic describes the latest updates to a product for a specific release. In
the short description, you can mention one or more of the following items:
— Two or three of the most important new features
— Where users can find information about other components in the product
— What component the new features pertain to
Bad
“What's new in Kitty Manager for z/OS?”
Version 8.3 continues to deliver a real return on investment to customers. Version 8.3
focuses on five areas: integration, open systems, autonomic systems, resiliency,
and ease of use. These highlights, and other enhancements to the Version 8.3
product, are summarized below: .
Good
“What's new in Kitty Manager for z/OS?”
Version 8.3 enhancements focus on five areas: integration, open systems, autonomic
systems, resiliency, and ease of use.
.
28
5/18/2016

29. Reference topic: Troubleshooting
• A troubleshooting container topic should introduce the collection of
troubleshooting topics.
• Container topics serve as navigation aids.
• Provide enough information so that users understand the type of
troubleshooting topics that will follow the container topic.
Bad
“Troubleshooting the resource manager”
This section provides troubleshooting information to help you solve some
common resource manager problems.
Good
“Troubleshooting the resource manager”
Resource manager failures can include problems with the database, secure
sockets layer (SSL), and other component connections of the kitty
management system.
29
5/18/2016

30. Quiz: Correct the short descriptions
Starting the system administration client on AIX
— You can start the system administration client on AIX.
— You can start the system administration client so that you can manage
your deployment server. Use the cmadmin.sh command to start the
server.
Search collections
— A search collection is a set of data sources that users can search with a
single query. You can build new collections or continue to update existing
collections. A search collection can contain data from the following
sources:
— A search collection is a set of data sources that users can search with a
single query. A search collection can contain data from Web sites, file
systems, and databases.
30
5/18/2016

31. Quiz: Correct the short descriptions
autorestart - Auto restart enable configuration parameter
— Specifies whether the database manager can automatically call
the restart database utility.
— This parameter determines whether the database manager can
automatically run the restart database utility when an application
connects to a database.
User Preferences: Mail window
— From here, set your mail window preferences.
— Use this window to select a default address book, to change how
you save sent mail, or to specify how you forward and receive
mail automatically.
31
5/18/2016