Topic-oriented writing at McAfee
Transcript of Topic-oriented writing at McAfee
© 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