View
226
Download
0
Category
Tags:
Preview:
Citation preview
Introduction to Topic-Based Writing
NCR Information Engineering
NCR Internal Use Only
Topic-Based Writing 2
About this presentation
Purpose: – To provide an introduction to topic-based
writing• What it is
• How we will use it
• How we will do it
• The tools that make it possible
• Requirements
– To help writers get comfortable with this new approach
NCR Internal Use Only
Topic-Based Writing 3
About this presentation
Intended Audience: – NCR Information Engineers
– Other content creators
– Users of Author-it
NCR Internal Use Only
Topic-Based Writing 4
About this presentation
• Assumptions about you: – Familiar with technical writing
– Motivated to improve technical content
– Interested in learning about topic-based writing
What is Topic-Based Writing?
An Introduction to Topic-Based Writing
NCR Internal Use Only
Topic-Based Writing 6
Before topic-based writing…
• Technical writers created books– The term “book” implies paper-based manuals, which was
the most common format
• Page count measured the quality (instead of simply quantity) of technical content
• Technical writers were encouraged to document everything– This approach contributes to increasingly thick manuals
NCR Internal Use Only
Topic-Based Writing 7
Background
• Topic-based writing is a somewhat new approach to structuring information– Its roots are in the concept of “minimalism” (John Carroll)
– It gained popularity when online help systems emerged in the mid 1990s
• Built on the ideas that readers:– want to reach their goal quickly and successfully
– do not read information for pleasure’s sake when accessing instructions
– are slowed down and distracted by extraneous information
NCR Internal Use Only
Topic-Based Writing 8
Background
• Instead of writing in book form, topics are self-contained, stand-alone bits of information– Think of topics as “doc-lets”
• Book form– Topics are saved in flat files
• Topic form– Topics are saved as records in a database
NCR Internal Use Only
Topic-Based Writing 9
A comparison
Topic-Based Authoring
• Multiple authors per information product
Book-Based Authoring
• One author per book
NCR Internal Use Only
Topic-Based Writing 10
A comparison
Topic-Based Authoring
• Multiple authors per information product
• Topics serve multiple products and audiences
Book-Based Authoring
• One author per book
• Books serve a single product and audience
NCR Internal Use Only
Topic-Based Writing 11
A comparison
Topic-Based Authoring
• Multiple authors per information product
• Topics serve multiple products and audiences
• Content development is iterative
Book-Based Authoring
• One author per book
• Books serve a single product and audience
• Content development is linear
NCR Internal Use Only
Topic-Based Writing 12
A comparison
Topic-Based Authoring
• Multiple authors per information product
• Topics serve multiple products and audiences
• Content development is iterative
• Presentation layout can be template-driven
Book-Based Authoring
• One author per book
• Books serve a single product and audience
• Content development is linear
• Presentation layout requires manual work
NCR Internal Use Only
Topic-Based Writing 13
A comparison
Topic-Based Authoring• Multiple authors per
information product• Topics serve multiple
products and audiences• Content development is
iterative• Presentation layout can
be template-driven• Well suited for modular
hardware/software products with short lifecycle or long life span
Book-Based Authoring• One author per book• Books serve a single
product and audience• Content development is
linear• Presentation layout
requires manual work• Well suited for highly
technical or one-of-a-kind products with a long development cycle and/or short life span
NCR Internal Use Only
Topic-Based Writing 14
Characteristics of topic-based writing
• Information is chunked– Solid technical writing already emphasizes and uses this
approach
• Uses consistent writing style and phrasing– Reliance on the style guide is critical
• Many contributors to each information product, but the reader can’t tell – The singular voice
NCR Internal Use Only
Topic-Based Writing 15
Characteristics of topic-based writing …cont’d
• Topics can be pulled together in any combination, to meet the needs of different users– Different output forms (web, online help, print)
– Different audiences (internal vs. external, or beginner, novice, advanced)
• Authors create content without anticipating how it will be used– This enables reusable content!
NCR Internal Use Only
Topic-Based Writing 16
Benefits of topic-based writing to IE
• SMEs can review topics as soon as they are written– Do not have to wait for completion of book
– This fits more closely with Agile software development methodologies
• Consistently structured topics:– Help users navigate content
– Make it easy to reuse content in multiple deliverables
NCR Internal Use Only
Topic-Based Writing 17
Terms you’ll also hear
• Structured authoring– definition
• Modular writing
• Single sourcing– Maintaining a single, definitive source of content. Reuse is
merely a benefit of single-sourcing.
• Content reuse/Reusable Content– A piece of information that is unconstrained, and not tied
to one deliverable type
NCR Internal Use Only
Topic-Based Writing 18
Terms you’ll also hear… cont’d
• DITA (Darwin Information Typing Architecture)– A standard for defining online help and support information
in XML using a DTD schema that covers "topic," "concept," "task" and "reference" categories.
• Minimalism– An approach to information development using task-based
chunks of information
• Information typing– Separating content into easily identifiable chunks of
information
NCR Internal Use Only
Topic-Based Writing 19
Topic-based writing motto
• Write it once, review it once, use it over and over again
Topic
Write
Topic
Review
Topic
Use
TopicTopic
TopicTopic
TopicTopic
TopicTopic
NCR Internal Use Only
Topic-Based Writing 2023-04-19 NCR Confidential 20
Reusable content
TrainingContent
ReleaseBulletin
Info
Parameters TechnicalWhitepapers
TechnicalKnowledge
BaseArticles
Web Content
TechPublications
???
Topics in the database
Topic-Based Writing in the Real World
An Introduction to Topic-Based Writing
NCR Internal Use Only
Topic-Based Writing 22
Why should I care about topic-based writing?
• Many industry-leading companies are moving to topic-based writing for their technical documentation– Using the latest technology and methods presents a career
growth opportunity
• This method has the potential to ease the workforce shortages we face
• You can concentrate more on the content, not how it looks when published
• You get to collaborate more closely with your colleagues
NCR Internal Use Only
Topic-Based Writing 23
How does topic-based writing relate to Author-it?
• Topic-based writing is a METHOD or APPROACH
• Author-it is simply a TOOL that helps put the method into place – Author-it is a content management system (CMS)
– It contains a SQL database
– Each topic is a record in the SQL database
– Because topics are stand alone units, you can reuse them in multiple ways
NCR Internal Use Only
Topic-Based Writing 24
Here’s a look at Author-it
NCR Internal Use Only
Topic-Based Writing 25
And here are some topics
NCR Internal Use Only
Topic-Based Writing 26
And here are some topics in a “book object”
NCR Internal Use Only
Topic-Based Writing 27
How does it affect my day-to-day job?
• Less focus on formatting• More focus on content• More collaboration between writers• Decreased focus on ownership of books• Increased need to adhere to the Style Guide• New tool to learn• Different process for publishing and archiving• More chance to reuse existing content• Increased ability to create multiple output formats with
a minimal amount of work
NCR Internal Use Only
Topic-Based Writing 28
Publishing and Archiving Changes
• Publishing:– Author-it includes release state flags that you must apply
to each topic as it matures through the development cycle towards publication:
What are Topics?
An Introduction to Topic-Based Writing
NCR Internal Use Only
Topic-Based Writing 30
Let’s discuss topics…
According to JoAnn Hackos, each topic:
• has a title to name its purpose
• contains enough content for someone to begin and complete a task, grasp a basic concept, or look up critical reference information
• has a carefully defined set of the basic content units that are required and accommodates other optional content
NCR Internal Use Only
Topic-Based Writing 31
What is a topic?
An information chunk that:
• answers one question– How do I…?
– What is...?
– What went wrong…?
• has a heading
• can stand alone — makes sense in any context
• points to related topics (if appropriate)
NCR Internal Use Only
Topic-Based Writing 32
How does a topic stand alone?
Topics = Building Blocks– make sense on their own (are context-free)
– can be assembled in different ways
– avoid transitions at beginning or end (“see the following table”, etc.)
– are easy to read and comprehend (always spell out acronyms or use a pop-up definition)
NCR Internal Use Only
Topic-Based Writing 33
How does a topic stand alone … cont’d
Topics = Building Blocks– are format-free (use tagging to identify elements such as
heading, body, bullet-list item, numbered-list item)
– use standard phrasing that conforms to the Style Guide (“To install the widget:”; “For more information, see…”)
NCR Internal Use Only
Topic-Based Writing 34
How long should a topic be?
• As long as it needs to be to answer one question– (Does not have to fit on a single screen – scrolling is
allowed.)
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
About the WidgetThis 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 the WidgetThis topic is longer because of all the steps required.
1. Do this.
2. Do that.
Topic 2
NCR Internal Use Only
Topic-Based Writing 35
Installing the WidgetThis topic is longer because of all the steps required.
1. Do this.
2. Do that.
How long should a topic be …cont’d
• As short as it can be while still making sense all on its own– Includes all the information it needs to be understood
without additional context
– Is not cluttered with extra information that may apply to one context but not another
Cleaning the Widget
Put the entire widget-cleaning procedure here, unless it varies according to context. Then you need more than one topic.
Topic 1 Topic 2
Cleaning the Widget in Zero Gravity
Whatever you do, don’t use a liquid solvent. Use antiseptic wipes only.
1. Do this…
NCR Internal Use Only
Topic-Based Writing 36
Why write in topics?
Benefits to Users:– fits the non-sequential way they use technical information
– lets them get right to the information they need, without having to read a bunch of stuff they don’t need
– gathers information into neat little packages that answer one question completely and succinctly
– helps them get their jobs done by supporting task-centric (vs. product-centric) documentation
– the information products they get can be customized to suit their information needs
NCR Internal Use Only
Topic-Based Writing 37
Why write in topics?
Benefits To Writers:– supports multi-writer collaboration
– enables information reuse (single-sourcing)
– makes it easier for us to create information products to support large solutions including more than one product
• some stuff from Passport, some stuff from TM, some stuff from WiseIP…
– reduces redundancy • information exists in only one place, so updated only once
NCR Internal Use Only
Topic-Based Writing 38
Don’t I already write in topics?
• Maybe…– Many seasoned technical writers already think about and
structure content in bite-sized chunks
• But… – working with FrameMaker (and Word to a lesser extent)
necessarily means that you think of content in book-based format
• And… – this workshop is meant to ensure that all NCR authors
share a common understanding of topic-based writing
The Three Topic Types
An Introduction to Topic-Based Writing
NCR Internal Use Only
Topic-Based Writing 40
The three topic types
Describes something.
Tells how to do something.
Usually includes numbered steps.
Gives details of interest about something to certain readers, often in list or table form.
Task
Concept
Reference
NCR Internal Use Only
Topic-Based Writing 41
Here’s another way to look at the three topic types
Task
Concept
Reference
Learning
Doing
Knowing
NCR Internal Use Only
Topic-Based Writing 42
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 about something
ReferenceTas
k
Conce
p
t
The Three Topic Types in Action
An Introduction to Topic-Based Writing
NCR Internal Use Only
Topic-Based Writing 44
Examples
• In this series of slides, you will see examples of the three topic types at work
Task
Concept
Reference
NCR Internal Use Only
Topic-Based Writing 45
About conference callsUse a conference call to speak with more than two people in two different locations at the same time. Use one of the following types of conference calls to speak with multiple people.
Three-way conference callsThree-way conference calling connects two other people to a call.
Multi-line conference callsMulti-line conference calling connects you to more than two but fewer than eight other people on a call.
Dial-in conference callsDial-in conference calling uses a single conference call number to connect multiple people.
Concept
NCR Internal Use Only
Topic-Based Writing 46
ImageMark Passport is a remote capture solution for capturing check and image transactions at any of the following remote locations:
• the branch• an ATM• a commercial client
Passport capture then transmits the images and data to a central point where they are consolidated into larger units of work and passed on for further processing.Passport can also work as a front-end capture solution for an image-POD system, such as ImageMark Transaction Manager or ImageMark NCompass.
Concept
NCR Internal Use Only
Topic-Based Writing 47
Replacing the Inkjet Cartridge
When the endorsement print becomes light and difficult to read, replace the ink jet cartridge. When changing the ink jet cartridge, follow these steps:1. Turn off the power.
2. Open the cover.
3. Remove the ink-jet cartridge by pulling it up and out of its holder.
4. Discard the used cartridge.
5. Take the new cartridge out of its packaging and remove the protective tape.
6. Place the front of the cartridge down and into its holder.
7. Push down on the rear tab until it snaps into place.
Task
NCR Internal Use Only
Topic-Based Writing 48
Checking System MessagesCheck for system messages in case problems arose from the previous work cycle. To check system messages:1. In Task Manager, choose Diagnostics from the Utilities list.
The system displays the Diagnostics window.
2. Acknowledge all outstanding messages and take the suggested corrective action. For more information on handling error messages, see Troubleshooting.
3. Minimize Diagnostics. If error messages are received during the day, this icon will flash and beep to alert you.
4. Return to Application Manager.
5. Keep the Application Manager window open throughout the day to monitor and manage workflow. For more information, see Application Manager.
Task
NCR Internal Use Only
Topic-Based Writing 49
Hazardous Waste Drop-OffYou may drop off hazardous waste free of charge at your local landfill on the first Saturday of each month. The following items are accepted:
Reference
• Paint• Cleaning solvents• Non-functional electronics• Batteries• Deceased pets
NCR Internal Use Only
Topic-Based Writing 50
ImageMark Parameter Files – ASCII and Related Support Files
File Extension File Description
.dat ASCII data files – contain ImageMark keyword parameters
.lst List files – map ImageMark keywords associated with .dat files to compiled binary files
.prm Compiled ASCII data files
.trn ASCII Translator control files – contain relationship information between ImageMark keywords and the input (ASCII) and output (binary) file
.urn ASCII Untranslator control files – contain relationship information between ImageMark keywords and the input (ASCII) and output (binary) files
Reference
NCR Internal Use Only
Topic-Based Writing 51
Should you always separate the concept info?
• In some cases, it makes sense to combine topic types.
• If you have only a tiny bit of concept information, it will annoy the user to have to jump to another topic just to read a sentence or two.
• But if you have a lot of concept information, it will slow down the user who wants to get on with the task, so you need another topic.
NCR Internal Use Only
Topic-Based Writing 52
A Good Test for Separation
• If there is only one task associated with a concept, it might make sense to combine the concept info with the task.
• If there is more than one task, then you need to separate the concept info, to avoid repeating it.
NCR Internal Use Only
Topic-Based Writing 53
In an ideal world…
Users would:
• always find the right topic the first time
• never have to read anything irrelevant
• always get everything they need in one topic
NCR Internal Use Only
Topic-Based Writing 54
In the real world:
• Your users will always vary too much in their knowledge, experience, and needs for you to get it perfect.
• The best you can do is make a reasonable estimate of what a typical user might want in a topic.
NCR Internal Use Only
Topic-Based Writing 55
Okay, I get it. How do I do it?
1. Identify the task topics needed — based on user goals, not user interface. Hint: A task answers a “How do I?” question
2. Identify the concept and reference topics needed to support those tasks.
3. Provide navigation and structure to support users in finding information.
4. Create, assemble, and publish the topics (print, Web, Help).
NCR Internal Use Only
Topic-Based Writing 56
What makes a well-formed topic?
Four characteristics of well-formed topics:1. use heading syntax to communicate
info type
2. avoid significant mixing of info types
3. serve as a hub — point to related topics (if appropriate)
4. focus on one user question
NCR Internal Use Only
Topic-Based Writing 57
#1: Heading Syntax
A well-formed topic uses heading syntax to communicate information type.
Info Type: Example:
Concept About the Entry Status Utility
Task Running the Entry Status Utility
Reference Entry Status Utility Command Syntax
NCR Internal Use Only
Topic-Based Writing 58
#2: Avoid mixing of info types
A well-formed topic avoids significant mixing of information types (beyond a few sentences).
Look out for:– Concepts with steps embedded
– Tasks with lengthy background embedded
– Reference tables with concepts embedded
NCR Internal Use Only
Topic-Based Writing 59
Example: Mixed info types
Installing Server Software1. Enter the IP addresses for the server.2. Click Next.
The system displays the Select Features dialog.
3. This dialog allows you to select the features you want to install with the server, and the software install directory. Select any of the checkboxes that correspond to the features you want to install.• Passport Consolidation Server Workflow--Base software
required for processing deposits in Consolidation Server.
• Passport Consolidation Server Database--The SQL database that contains deposit item records and images.
There’s a step in here somewhere… but mostly it’s Concept info
NCR Internal Use Only
Topic-Based Writing 60
Example: too much reading!
Installing Server Software (cont’d)4. Choose the destination directory using the Browse
feature.Important: If possible, use the default installation directory (for example, C:\
CServer). This makes it easier for technical support to diagnose and resolve issues in your system. If you cannot use the default installation directory, your destination directory must meet the following requirements:
– It cannot reside more than one level from the root directory.– It cannot contain spaces in the name.
5. Click Next.The ImageMark Passport Consolidation Server software and database are
installed on the server.A dialog asks if you want to install the Consolidated Report Generator.Note: The Consolidated Report Generator enables you to produce reports on
deposits stored in the Consolidation Server database.
6. Choose whether you want to install the Consolidated Report Generator utility by selecting Yes or No.
7. When asked to restart the computer, click Restart.
What can I replace with a popup?
NCR Internal Use Only
Topic-Based Writing 61
#3: It serves as a hub
A well-formed topic serves as a hub, pointing to related topics.– It directs you to where you want to go next
– It lets you find your way back, without getting lost in hyperspace
NCR Internal Use Only
Topic-Based Writing 62
#4: It answers one question
A well-formed topic answers ONE user question.– As fully as the user needs
– Only as fully as the user needs
Minimalism
NCR Internal Use Only
Topic-Based Writing 63
Makeover example – Before
About System PasswordsAll passwords in the Passport parameters are encrypted, including the default ones included in the properties just installed. This means that to change a default password, you cannot simply type the new one into your override file.Passport provides a new ANT script to encrypt password text for use in property files. You use this script in the same way as other ant scripts, but supply the plain-text password on the command line:1. Open a command prompt.2. Navigate to the Passport install directory (C:\Program Files\NCR\CPWE).3. Execute the following ANT command, replacing “password1” with your desired
characters:4. ant encrypt.password -Dvalue=password15. Cut (Ctrl + C) the resulting encrypted text from the command window.6. Paste the encrypted characters into the override file.
There are some temporary plain-text passwords used in files like build.properties which you must remember to delete when the installation is complete.
NCR Internal Use Only
Topic-Based Writing 64
Makeover example – After (1 of 2)
About System PasswordsAll passwords in the Passport parameters are encrypted, including the default ones included in the properties just installed. This means that to change a default password, you cannot simply type the new one into your override file.Passport provides a new ANT script to encrypt password text for use in property files. You use this script in the same way as other ANT scripts, but supply the plain-text password on the command line.There are some temporary plain-text passwords used in files like build.properties which you must remember to delete when the installation is complete.
See Also:Encrypting Password TextDeleting Temporary Passwords
NCR Internal Use Only
Topic-Based Writing 65
Makeover example – After (2 of 2)
Encrypting Password TextTo encrypt password text for use in property files:1. Open a command prompt.2. Navigate to the Passport install directory (C:\Program Files\
NCR\CPWE).3. Execute the following ANT command, replacing “password1”
with your desired characters:ant encrypt.password -Dvalue=password1
4. Cut (Ctrl+C) the resulting encrypted text from the command window.
5. Paste the encrypted characters into the override file.
See Also:About System Passwords
NCR Internal Use Only
Topic-Based Writing 66
Writer checklist
Get an Author-it user accountComplete this workshopSchedule a one-on-one with Susan/Jody
NCR Internal Use Only
Topic-Based Writing 68
Books• 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.
NCR Internal Use Only
Topic-Based Writing 69
Webinars
• https://xmetalevents.webex.com View All Recorded Events
NCR Internal Use Only
Topic-Based Writing 70
Web sites
• Author-it
Recommended