The Golden Rules (2–5)€¦ · Executive managers (CEO, CFO, CMO, COO), LoBmanagers, mid-level managers, power users, users, and consumers STAKEHOLDERS COMPETENCIES Keep the business-supporting

(c) 2007 - 2018 Leah Guren (Cow TC) for STC 1

1

Welcome to TechComm Fundamentals Bootcamp, Session 2

THE SESSION WILL START IN A FEW MINUTES.MUTE YOUR PHONE, PLEASE!

If you do not have a mute button on your phone, use the green phone handset button on the top left of your screen.

If you are listening to the audio via a phone line, turn your computer speakers down or OFF.

The Golden Rules (2–5)

Four more key concepts

of theory and application.

TechComm Fundamentals Bootcamp, © 2017 Leah Guren2


TechComm Fundamentals Bootcamp, © 2017 Leah Guren

Homework Review

� Didn’t pay attention to homework rules:• missed deadlines

• wrong file formats

• wrong information (no specific issues)

� Missing introductions and pictures in Moodle.

� Still calling yourselves tech writers.

� The profession is Technical Communication

(not Communications):• think process, not thing

• wrong terminology makes you appear inexperienced

3


Homework Review, cont.

� Pompous and stuffy writing:• one (as a pronoun)

• ensure

� Too much passive voice:• NO: “There are rules that I need to review.”

• YES: “I need to review rules.”

� Incorrect capitalization:• use title capitalization for headings

• always capitalize proper nouns

• don’t get sloppy in emails

4



Homework Review, cont.

� Missing commas:• “By meeting these objectives my hope is…”

• “When I write long sentences I try to add…”

� Incorrect punctuation with parentheses:� NO: “…more clear (and best for the customer.)”

� YES: “…more clear (and best for the customer).”

� Run-on sentences

� Hidden strong verbs:� NO: “XXX is an influence on YYY…”

� YES: “XXX influences YYY…”

� Are you ready for more GRs?

5

#2: Know your audience.





Know your audience.

� Look at demographics:• age

• education

• language (English) skills

� Consider domain and product knowledge:• How much do they know about the field?

• Do they have product experience?

� Make safe assumptions:• domain knowledge: you don’t need to explain what a

fused crown is to a dentist

• expertise: you can assume that a sys admin knows

how to access Regedit

8



Know your audience, cont.

� Distinguish the user from the domain.

� Identify special needs:• vision impaired, color blind

• reduced small motor skills

• low literacy

� Find ways to get this info:• direct customer contact

• internal sources (marketing, tech support,

customer training, etc.)

• 7but don’t rely on SMEs!

9


Create personas. Create personas.

� A persona is a tool:• you can’t talk to a statistic

• generic audience profiles tend to be too broad and

vague

• more concrete profiles lead to better editorial

decisions

� Create a persona for each major group of

users:• for example: sys admin, new user, power user

• no more than four

10



Sample Persona Sample Persona

Brenda Ang

Human Resources Director

Brenda is 33, married, and has no

children. She lives on Vashon Island

and commutes in to Seattle by ferry

three times a week. On the other two

days, she works from home.

Brenda has been at Bosco Services for six years, but she

only became the HR director three months ago. She feels

pressured in her job, and does not have a lot of time to

waste learning how to use the SecuraChek software. Bosco

Services has been a SecuraChek customer for the past

three releases, but Brenda has not used the software

before. Her main tasks with SecuraChek are711

© 2015 SAP SE. All rights reserved.

JOB RESPONSIBILITIES

Background: Age: 57

Married, 3 kids

BSC in Computer Science + MA in Information Systems

Job Title/Role: CIO, Green Foods Inc.

(supermarket chain)

MAIN GOALS

Casual Jane

Proactive

Work in team

Global focus

Innovative

Power Jane

Reactive

Lone Fighter

Local focus

Conservative

PAIN POINTS

“I must support the business, keep users happy and management satisfied, with minimum risks and interruptions, all with a stagnating budget.“

� Responsible for the budget of the IT organization

� Responsible for 100 IT experts (project managers, developers, administrators, etc.)

� Responsible to provide IT solutions

� Responsible for the IT roadmap (long-term plans)

NEEDSExecutive managers (CEO, CFO, CMO, COO), LoB managers, mid-level managers, power users, users, and consumers

STAKEHOLDERS

COMPETENCIES

� Keep the business-supporting systems up and running

� Provide LoB (line-of-business) and consumers with the right tools

� Provide good service to customers (users from LoB) and consumers

� Many requirements and change requests from LoB

� Complex technical landscape

� LoB buy/build their own apps if not satisfied with IT’s solution

� Stagnating budget

� I need more time

� I need more people

� I need to cut costs

� I need less complexity and risks in my landscape

� I need partners that I can totally rely on

� I would like my organization to generate money not just costs

Name: John Kahn

� I need our applications to run everywhere (web, mobile, etc.)

� I need my staff to adopt to new technologies

12



Perform audience needs analysis.

� Where does the user need to use the product?

� What does the user need to do with the

product?

� Based on that, what does the user need to

know about the product?

� Use scenarios.

This is the first step in understanding what

to document and to do it!

13

#3: Highlight hazards.






Highlight hazards.

� Find hidden hazards (warnings, cautions, etc.)

through scenarios:• what will happen if7?

• why should they7?

� Rank hazards by severity (signal word):• Danger: death or serious injury• Warning or Caution: damage to HW or data (however,

users don’t understand fine distinctions, so pick only one)

• Note: unexpected performance (system anomaly, not user action or info you think is important)

� Make hazard visually clear:• signal word/icon separate from text (hanging indent)• group together


Highlight hazards, cont.

� Use a simple do/do not statement:• NO: “The front panel should be opened before…”

• YES: “Open the front panel before…”

� Explain ramifications and work-arounds:• if this is a common mistake

• if this is life-threatening (medications, etc.)

• if the audience has a low compliance rate (re: Hofstede’s Cultural Dimensions theory)

� Place hazards appropriately:• not after

• not too far before



Sample Hazard

Note: The unit may reach high temperatures. Care

should be taken to avoid contact with internal elements

until the unit has achieved sufficient thermo-adjustment.


#4: Break it out.



Antihistimine Comparison

Allegra (Fexofenadine; Aventis) is prescription only.

Allegra D is basically Allegra plus a decongestant in a

combination tablet (Aventis). Clarinex (Desloratadine;

Schering-Plough) is prescription only. However, Claritin

(Loratidine; Schering-Plough) became available as an

over-the-counter drug in December of 2002. Claritin D is

Claritin with a decongestant in a combination tablet

(Schering-Plough).



First, sort the clothing by color and fabric weight. Next,

go through all garments carefully to empty pockets.

Also look for any loose buttons that may come off in

the wash. Then, make sure that you read the care

labels for washing instructions, especially for any new

garments that you haven’t already laundered. Now,

find any stains or heavily soiled areas (check collars,

cuffs, etc.) and pre-treat them according to the

instructions on the stain remover product. Then, start

the wash, making sure to use the right temperature for

the clothes. In general, light colors and sturdy fabrics

(such as cotton) can take hotter temperatures.

22



Break it out and provide structure.

� Users don’t read blocks of text!

� Visual structure is how content within a topic is

arranged.

� It allows users to read quickly and understand.

� Think of:• headings

• tables for values and specs

• numbered lists for procedures and instructions

• bulleted lists for non-sequential information

• flowcharts for branching

23


Organize the overall document.

� Part of break it out is the document organization.

� Organization is how different topics are arranged

in the overall content (document, website, etc.).

� Some organization schemes are:• common to less-common tasks

• high level to low level

• workflow (multiple tasks in a particular order)

• problem/solution

• classification or category

• alphabetical

• 7and many more

24


#5: Don’t write blind.



We are supplying a software patch that should take care of your Registry corruption problem. After you install the patch (copy the files to the installation directory), reset access value to single copy. Since you are running an old version (Windows 95 with French support), change the keyboard setting for the proper ASCII code page. This is in the Control Panel. The next time you run the software, you will see the new access check-box in the Configuration dialog box. Use this (default) with single copy settings.

26


Background FilterIf selected, background filtering is allowed.



Understand what you’re writing.

� You must learn the product and the domain.

� Never rely on second-hand information:• see it, touch it, use it

• if you can’t do it, you can’t explain it

� Use your own intelligence and logic!

� But there’s more7

28



Understand the project!

� Never start working on something until you know:

• the client

• what they are trying to accomplish with this info

• how they are monetizing the info

• how will the user get the info

• what the user is supposed to do with the info

� Ask yourself: is this the right deliverable for this purpose?

� Think and ask (open questions and scenarios): remember

that the client wants is not always what the users need.

I can’t read your mind! Provide this info from now on!

29


Session 2: Discussion & Homework

� Moodle discussion topics:• Why is audience analysis the logical start

of any project?

• Have you ever read a product manual that

seemed to be written blind? What made it

appear so?

• How is GR#4 an example of how TC

writing differs from other kinds of writing?

� Homework: Rewrite the big block of

text paying special attention to GRs

#2–5. For #5, embed questions to the

SMEs in [brackets].

30

Documents

The Golden Rules (2–5)€¦ · Executive managers (CEO, CFO, CMO, COO), LoBmanagers, mid-level managers, power users, users, and consumers STAKEHOLDERS COMPETENCIES Keep the business-supporting