the golden rules (2–5)€¦ · executive managers (ceo, cfo, cmo, coo), lobmanagers, mid-level...
Post on 30-Apr-2020
5 Views
Preview:
TRANSCRIPT
(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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 2
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
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 3
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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.
TechComm Fundamentals Bootcamp, © 2017 Leah Guren6
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 4
TechComm Fundamentals Bootcamp, © 2017 Leah Guren7
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 5
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 6
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 7
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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.
TechComm Fundamentals Bootcamp, © 2017 Leah Guren14
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 8
TechComm Fundamentals Bootcamp, © 2017 Leah Guren15
TechComm Fundamentals Bootcamp, © 2017 Leah Guren16
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 9
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
TechComm Fundamentals Bootcamp, © 2017 Leah Guren17
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
TechComm Fundamentals Bootcamp, © 2017 Leah Guren18
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 10
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.
TechComm Fundamentals Bootcamp, © 2017 Leah Guren19
#4: Break it out.
TechComm Fundamentals Bootcamp, © 2017 Leah Guren20
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 11
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).
TechComm Fundamentals Bootcamp, © 2017 Leah Guren21
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 12
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 13
#5: Don’t write blind.
TechComm Fundamentals Bootcamp, © 2017 Leah Guren25
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 14
Background FilterIf selected, background filtering is allowed.
TechComm Fundamentals Bootcamp, © 2017 Leah Guren27
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
(c) 2007 - 2018 Leah Guren (Cow TC) for STC 15
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
TechComm Fundamentals Bootcamp, © 2017 Leah Guren
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
top related