introduction to topic-based writing ncr information engineering

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




Intended Audience: – NCR Information Engineers

– Other content creators

– Users of Author-it




• 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



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



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



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



A comparison

Topic-Based Authoring

• Multiple authors per information product

Book-Based Authoring

• One author per book



A comparison



• Topics serve multiple products and audiences



• Books serve a single product and audience



A comparison




• Content development is iterative




• Content development is linear



A comparison




• Content development is iterative

• Presentation layout can be template-driven




• Content development is linear

• Presentation layout requires manual work



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



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



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!



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



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



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



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


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




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



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



Here’s a look at Author-it



And here are some topics



And here are some topics in a “book object”



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



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?




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



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)



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)



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…”)



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



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…



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



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



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




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



Here’s another way to look at the three topic types

Task

Concept

Reference

Learning

Doing

Knowing



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




Examples

• In this series of slides, you will see examples of the three topic types at work

Task

Concept

Reference



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



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



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



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



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



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



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.



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.



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



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.



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).



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



#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



#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



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



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?



#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



#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



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.



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



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



Writer checklist

Get an Author-it user accountComplete this workshopSchedule a one-on-one with Susan/Jody



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.



Webinars

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



Web sites

• Author-it

introduction to topic-based writing ncr information engineering

Documents

topicbased writing slide

background topicbased

audiences bookbased

iterative bookbased

technical writing

book slide

paperbased manuals

ncr information engineers