© 2009 McAfee, Inc.

Creating documentation using topic-oriented writing

John Sarr, Senior Technical Writer

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

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

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/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

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

5/18/2016

Topic Type—Comparing info type schemasInfo 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

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

5/18/2016

Applying topic titles to bring out the theme of a topicCategory 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

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 ControlParallel 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 QuantizerUse 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 AnalysisAutomatic Reports With Moving-Window Detection

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

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

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

5/18/2016

Example 1: Redoing a concept topicBefore

Categorical headings

Two or more topics

Diffuse: References to more info

After

Topical heading

Single topic

Concentrated: Self-contained info

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

© 2007 McAfee, Inc.

Short descriptions

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

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

First paragraph of a topic19

5/18/2016

Link text in hover help20

5/18/2016

Short description text in child links21

5/18/2016

Internet search results from Google22

5/18/2016

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

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

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

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

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

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

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

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

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