1. business and industrial
2. business operations
3. management
4. project management

September 2013
The Magazine of the Society for Technical Communication
Project Management
and the Technical
Communicator:
Why It Works 6
9
13
Style Guides: Personal and
Practical Tips on How to
Get Started and Keep Going
16
Lessons Learned in Marketing
Communication Over Barbecue
20
te ed
Do You Really Want to Say That?
Writing in a World of Jargon,
Slang, Corporate Catchphrases,
and Technical Pseudo-Terms
M
em
16 be
$1 Se rs
pt hi
9
r 5
p
en d
e
i
m Op
Ew s
c
be e
al o
u
r nt
r ns
a
An Interview with Owner’s Manual
Costar Marcus Hunt
Information. Anytime, Anywhere.
A Complete Suite of Tools to Create Professional Documentation
for Any Audience, Language or Format
Showcase True Single-sourcing
Social Collaboration
Right-to-Left Language Support
Print Output
HTML5 Output
Mobile Output
* Don’t Forget Great Tech Support!
Download Free Trial // Learn More // madcapsoftware.com
TRAINING, CONSULTING AND TRANSLATION SERVICES
TRAINING
CONSULTING
TRANSLATION
Maximize your return on
investment with on-site and
web-based training, taught by our
MAD Certified Flare experts.
Find the right consultant for short
and long-term projects. O
r start
consulting for MadSkills with a
MAD Certification.
MadTranslations specializes in
individual projects or complete
end-to-end translation and
localization solutions.
© 2013 MadCap Software, Inc. All rights reserved. MadCap Software, MadTranslations, Flare, MadPak, Madtranslations.com, MadCapSoftware.com
and the MadCap Software logo are registered trademarks of MadCap Software, Inc. Other marks are the properties of their respective owners.
©2013 GrapeCity, inc. All rights reserved. All products
and brand names are trademarks and/or registered
marks of their respective holders.
IN THIS ISSUE
13
9
September 2013
Volume 60 | Issue 8
5
From the Editor
Features
Project Management
6
Project Management and the Technical Communicator:
Why It Works
By Liz Herman
The skills we refine over time
as technical communicators
have a critical place in project
management. This article
explains how and why it works.
Conversations
9
An Interview with Owner’s
Manual Costar Marcus Hunt By Nicky Bleiel
www.stc.org
STC’s president interviews
Marcus Hunt, costar on the
new AMC television program
Owner’s Manual, which takes
a familiar dichotomy of
human nature—that some
people read instructions
when assembling furniture or
installing home electronics,
while others don’t—and
accelerates it in scale and
riskiness as two men operate
powerful and potentially
dangerous vehicles (trains,
planes, race cars, a sailing
ship) with which they were
previously unfamiliar. As the
instruction-manual reader on
the show, Marcus explains his
appreciation for the work of
technical communicators in
this interview.
Writing and Editing
13 Do You Really Want to Say That? Writing in a World of Jargon, Slang,
Corporate Catchphrases, and Technical Pseudo-Terms
By Harry Calhoun and Dave Wright
What are jargon, slang,
catchphrases, and pseudoterms? How can we avoid them
when writing for a professional
audience? This article defines
the terms and provides
guidelines for clear writing.
1
Continue Your Learning
with STC Education!
STC offers a wide variety of online education
options throughout the year. Whether you
need an introduction to a subject, an in-depth
review, or just a brush-up, STC has what you
need. Advance your career with STC’s varied
collection of online education.
Live Web seminars
Multi-week online courses
Virtual conferences
Recorded webinars
And free archived seminars
(members only)
IN THIS ISSUE
20
16 Style Guides: Personal and
Practical Tips on How to Get
Started and Keep Going
By Karina Lehrner-Mayer
A practical guide for
documentation teams in creating
documentation guidelines, this
article helps team leaders and
writers without a formal style
guide to start thinking about
creating one. It also includes
tips for teams with existing
style guides who would like to
increase acceptance and use of
their guides.
Marketing Communication
20 Lessons Learned in Marketing
Communication Over Barbecue
25
32
Society Pages
22 The 2012–2013 Salary Database
Is Now Available for Download
and Purchase
Advancing Your Career
28 Advancing Your Career through Progressive Information Disclosure
By Jack Molisani
22 2014 Membership Season Now Open
23 Reminder of Deadlines for Awards and Honors
23 Have You Seen STC’s Notebook Lately?
24 Intercom’s 2014 Editorial
Calendar
DEPARTMENTS
FYI
31 Mark Your Calendar
Organization Events Across the Globe
My Job
32 Dear Technical Writing: A Love Story
By Anonymous
24 STC Communities and Staff Win APEX Awards
ADVERTISERS
By Kevin Cuddihy
Do you send or receive a lot
of marketing emails? If so, you
know that email marketing can
be an annoyance or an important
method of communication. It
can be spam or a great sales
or informational tactic. The
author uses an example from a
restaurant to show how to keep
email communications on point
and your audience happy to hear
from you.
www.stc.org
COLUMNS
The Strategic IA
25 Play to Your Strengths, Shore Up Your Weaknesses:
The Dynamic Duo of Project
Manager and Strategic
Information Architect
By Andrea Ames and Alyson Riley
C3
Adobe
C2
Doc-To-Help
15
Johns Hopkins University
C4
MadCap Software
2
STC Education
30
STC Membership
4
Summit@aClick
3
Did You Miss
the Summit?
Don’t miss this second
chance at attending the
Summit—from the privacy
of your home or office!
You can “attend” all the 2013 sessions
that interest you . . . at a time and
place of your choosing and without
having to travel.
SUMMIT@aClick lets you attend the conference you missed! Content of almost every session
was captured (audio and visuals) and will be available at the STC Live Learning Center.
Members who did not attend the Summit can purchase SUMMIT@aClick now—see the STC
website for details! STC is the only meeting in the technical communications field that
offers this ability to attend the conference sessions without having to travel.
Note: SUMMIT@aClick was included in the full registration fee for the Summit. Attendees should
have received an email with username and password.
SUMMIT@aClick
MEET THE STAFF
A Note from the Editor
This month’s Intercom includes articles and
columns focused on project management, writing and
editing, marketing communications, career advancement,
and an interview by President Nicky Bleiel with the costar
of AMC’s new show Owner’s Manual, Marcus Hunt. If you
haven’t seen or heard of this show yet, Owner’s Manual
takes a familiar dichotomy of human nature—that some
people read instructions when assembling furniture,
installing home electronics, or operating software, and
others don’t—and accelerates it in scale and riskiness as two men operate
powerful and potentially dangerous machinery (e.g., trains, planes, race cars,
a sailing ship) with which they were previously unfamiliar. As the instructionmanual reader on the show, Marcus enthusiastically explains his appreciation
for the work of technical communicators in this interview.
In the feature article, Liz Herman describes why the fields of project
management and technical communication work so well together. She uses
traits described in the Project Management Institute’s Body of Knowledge
(PM–BOK)to compare the professions. Harry Calhoun and Dave Wright
offer suggestions on writing in a world of jargon, slang, corporate catchphrases, and technical pseudo-terms and how can we avoid them when
writing for a professional audience. Karina Lehrner-Mayer reminds
documentation teams of the importance of style guides and provides tips
for how to start and upkeep a guide. And finally, Intercom’s Assistant Editor
Kevin Cuddihy has written a fun article about marketing emails he received
from a barbeque restaurant chain that provide a lesson on how to keep
email communications on point and audience appropriate.
In the two columns published this month—The Strategic IA and
Advancing Your Career—we learn how to strengthen our professional
development and career opportunities. Like the feature article by Liz
Herman, Andrea Ames and Alyson Riley have paired up another tech comm
“dynamic duo”—project manager and strategic information architect.
They use Tom Rath’s StrengthFinder 2.0 as a tool to explain why effective
partnerships between PMs and IAs are important to the success of teams
and projects. In his column, Jack Molisani provides advice about how to
advance your career through progressive information disclosure, which is an
interaction design technique that allows technical communicators to provide
the right amount of information where, when, and how the user wants it.
Society news also in this issue and of interest to STC members: the 2014
membership season opens on 16 September, and there is a special member
appreciation rate for renewing members of $195 for a limited time. In
addition, the 2012–2013 Salary Database is now available for download and
purchase, and the Intercom 2014 editorial calendar has been published at
http://intercom.stc.org/write-for-intercom/editorial-calendar/. Take a look at the
themes of the issues planned for next year, and consider writing an article
on a subject of interest to you!
Intercom, the magazine of the Society for Technical
Communication, is published to provide practical examples
and applications of technical communication that will
promote its readers’ professional development.
Publisher Society for Technical Communication
Editor Elizabeth E. (Liz) Pohland
Assistant Editor Kevin Cuddihy
Contributing Editors
Scott Abel, Meet the Change Agents
Andrea Ames and Alyson Riley, The Strategic IA
Thomas Barker, The Academic Conversation
Nicky Bleiel, The Essentials
Marc Lee, Media Matters
Jack Molisani, Advancing Your Career
Neil E. Perlin, Beyond the Bleeding Edge
Linda Roberts and Lisa Pappas, All Access
Derek Ross, Ethics
Brian Still, Trends in Usability
Editorial Advisory Panel
Barrie Byron, Elizabeth (Bette) Frick (Chair),
John Hedtke, Jack Molisani, Andrea Wenger
STC Board of Directors
Officers
Nicoletta A. Bleiel, President
Kit Brown-Hoekstra, Vice President
Alan Houser, Immediate Past President
Jane Wilson, Treasurer
Alyssa Fox, Secretary
Directors Bernard Aschwanden, Ray Gallon,
Deanne Levander, Ben Woelk
Society for Technical Communication
9401 Lee Highway, Suite 300
Fairfax, VA 22031-1803
+1(703) 522-4114 | +1(703) 522-2075 fax
Send questions and correspondence to the editor at the above
address. General information about STC: stc@stc.org or
www.stc.org.
Address Changes: membership@stc.org
Intercom Editorial: intercom@stc.org
Reprint Permissions: www.copyright.com
Intercom (ISSN 0164-6206) is published 10 times a year
(monthly, except for August and December) by the Society
for Technical Communication, 9401 Lee H
­ ighway, Suite 300,
Fairfax, VA 22031-1803, a nonprofit educational organization,
as a service to its membership. Membership in STC includes a
subscription to Intercom. Periodicals postage paid at Fairfax,
VA, and additional offices.
Postmaster Send address changes to Intercom,
Attn: Membership, c/o Society for Technical Communication,
9401 Lee Highway, Suite 300, Fairfax, VA 22031-1803.
Copyright © 2013 by the Society for Technical
Communication. All rights reserved. Printed in the USA.
All articles in Intercom are copyrighted by the authors unless
otherwise indicated. Anyone interested in reprints, reproductions, or reuse must contact the authors for permission. To
advertise in Intercom, contact Stacey O’Donnell at
stacey.odonnell@stc.org, Society for Technical Communication,
9401 Lee Highway, Suite 300, Fairfax, VA 22031. Ph: +1(703)
522-4144; Fax: +1(703) 522-2075.
—Liz Pohland
liz.pohland@stc.org
www.stc.org
5
Project Management
and the Technical
Communicator:
By Liz Herman | Senior Member
www.shutterstock.com/My Life Graphic
Why It
Works
6
September 2013
Proj e ct Mana g ement
As a long-time technical communicator, the role I play
as a project manager and the reasons why I succeed in
project management make perfect sense to me. To others,
however, the connection is not so clear. The skills that we
refine over time as technical communicators have a critical
place in project management. In addition to the actual act
of communicating content skillfully, technical communicators work to understand what the users need and how
the users prefer to access and consume information. At
a microscopic level, we intimately understand the role
formatting plays in documentation, we know the questions
to ask of our subject matter experts to extract the detailed
answers, and we recognize the value of checking our
work once, twice, and three times over. At a macroscopic
level, we see firsthand how organizational culture affects
information sharing, we know the importance of keeping
stakeholders informed, and we can identify pain points
caused by communication breakdowns across an organization. We also do pretty well at communicating with tact and
diplomacy. These skills can be directly applied to the art of
project management and can even give us an advantage in
ensuring project success.
If you have not thought about project management
before, it is time to see how your skills as a technical
communicator can lead you to a project manager position.
About Project Management
Project management is about leadership, team building,
motivation, communication, negotiation, conflict
management, political and cultural awareness, trust
building, coaching, and decision making. These traits
are, in fact, listed as the necessary interpersonal skills of
a project manager in the Project Management Institute’s
(PMI) Guide to Project Management Body of Knowledge or
PMBOK (pronounced PIM-bock). Technical communicators possess these traits and exercise them on a daily basis.
Whether you are coaching a new editor, motivating yourself
to write a blog entry for your STC chapter website, or
leading a new release of online help, you are putting these
project management skills into practice each and every day.
Similar to STC’s dedication to advancing the field of
technical communication, PMI is a professional association
that is dedicated to advancing the field of project
management. Its members attend local chapter events
as well as national and international conferences. PMI
members can become certified Project Management Professionals (PMPs) similar to STC members becoming Certified
Professional Technical Communicators (CPTCs).
PMI bases its project management guidance around
five process groups called initiating, planning, executing,
monitoring and controlling, and closing. Within these
process groups are knowledge areas related to time,
cost, and scope, which are known as the triple constraint
in managing projects. There are also knowledge areas
related to communications management, stakeholder
management, and quality management among others.
www.stc.org
When I am asked about my own PMP certification and
involvement in PMI, I see the benefits of being a technical
communicator in every process group and in every
knowledge area.
Let us take the knowledge area of human resource
management as an example. In this knowledge area, the
project manager must acquire, develop, and manage a
project team. While the human resources department
within your organization can help you acquire and develop
your team, the management aspect falls largely in your lap.
As a technical communicator, you are most likely already
skilled at working with different personalities and you have
figured out how to motivate people to share information.
You understand the intricacies of working with virtual
teams and how to overcome cultural and geographic
barriers that can sometimes derail projects. Even if you
are not currently in a management role, your work as an
individual technical communicator is positioning you for
a project management role in your future. Keep in mind
that this management role extends beyond a technical
communication project. These skills can be applied to
implementation of a talent development program, to an
engineering software upgrade, or to the debut of a new
company website. The people skills that you already possess
can lead you to successfully managing a team for any of
these projects.
If you have not thought about
project management before, it
is time to see how your skills as a
technical communicator can lead
you to a project manager position.
The Voice of the Project
As a project manager, you serve as the voice of the project.
You will regularly communicate with the project sponsor,
stakeholders, executive leadership, your team, and your
customer. Once again, technical communicators are in
a great position to be project managers. Why? We are
expert communicators. We know how to take complex
information and make it accessible and understandable.
We think about how the weekly status report will look
and whether our end users will be viewing the report on a
mobile device or a laptop. This is one thing that definitely
differentiates us as project managers: We think about our
end users and their needs at all times. Who better to do a
needs analysis of an audience than a technical communicator? We can determine by completing a needs analysis
whether a two-page dashboard status report is sufficient
or if the stakeholders want the full 10-page PDF file with
all the details. We understand the benefit of asking our
team members what they need and when they need it. We
7
If you do not have experience
with budgeting, scheduling, or
managing scope, these might
be things to which you can gain
exposure through your current
work environment.
may not be the one actually designing the report, but we
have this knowledge that we can convey to the designer
that ultimately helps foster communication and delivery of
content across the project team. The PMBOK, in its section
on communications management, details these types of
considerations. It also highlights the communications
skills that are helpful for a project manager to possess:
active listening, fact-finding, educating, summarizing,
and outlining next steps. Do these sound like skills that
technical communicators possess? I think so too.
Within the past year, I was asked to implement a
mentoring program across the division in which I work. As
the project manager and voice of the project, I needed to
determine how best to communicate this new program to
employees. I understood that they would need guidance
as to how the program worked. Because of my technical
writing background, it was easy for me to recognize that
some type of online reference guide should be created
and made available and easily accessible to the program
participants. The guide explains the role of the mentor
and mentee, provides suggestions on possible topics, lists
resources, and clearly identifies who across the organization can answer questions. While I still needed to initiate a
project charter, manage the schedule, adhere to a budget,
and focus on quality, the communications aspect was made
simpler because participants had something, the guide in
this case, to reference.
influence. An organization’s political and cultural climate
can make or break communication efforts. As a technical
communicator, you are probably aware of how the climate
in your organization fosters or hinders communication. For
example, some colleagues may tend to hoard information
because it gives them power. Others may tend to be more
transparent with information because they see the value of
sharing. As a project manager, you need to possess skills to
maneuver through these challenges. As a technical communicator who reaches out to others for information, your
maneuvering skills at obtaining that information are most
likely already in place. You have worked with the stubborn
subject matter expert, tactfully demanded the software
release schedule, or presented a business case that shows how
technical communicators add value. All of these experiences
will help you in your role as project manager.
Beyond Communication
Why It Works
There is more to project management than communication. As a project manager, you do need to understand
the financial aspect of your project as well the schedule to
which it is aligned. You also need an understanding of the
scope of your project so that you can manage expectations
around the final deliverable. There is also a key component
of managing risk that you should understand as well. If
you do not have experience with budgeting, scheduling, or
managing scope, these might be things to which you can
gain exposure through your current work environment.
You might also try to gain this kind of experience through
a volunteer project outside of work. You could, for example,
manage a project for an event sponsored by your local
STC chapter. This would provide you with some initial
experience with budgeting and scheduling and overall
project management. The common trait shared among
technical communicators is that we are lifelong learners.
I witnessed this trait at this year’s STC Summit. It was
wonderful to be among a learning community. Therefore,
if you do not have this experience now, I know as a lifelong
learner that you can gain these skills to complement your
already-strong skill set as a technical communicator.
An additional interpersonal skill mentioned earlier
in this article and stated in the PMBOK is that of being
politically and culturally aware. This means that you have
a sense of the political climate and cultural climate of
the organization. The PMBOK calls this organizational
8
The technical communicator turned project manager
works because of the unique skill set that we bring to
the project. The interpersonal traits suggested by the
PMBOK are traits that we possess. They are traits that
we put into practice on a daily basis. Moreover, other
technical communicators have successfully made the
transition to the project manager position. Results from
an informal survey I conducted in July 2013 using Twitter
and SurveyMonkey shows that there are self-identified
technical communicators who are PMP certified. Some
reasons for their pursuit of the PMP certification include
owning a consulting business, using PMI principles to lead
projects that are more technical and complex in nature,
and using PMI’s communication principles to ensure
that everyone understands the project. PMP certification
is not a requirement for transitioning to role of project
manager. There are many projects that do not require a
PMP-certified project manager. What is required is that you
apply your technical communication skills because they
have positioned you to be a successful project manager. gi
Liz Herman (liz@lizherman.com), PhD, PMP, is a communications leader with 19 years of demonstrated achievements delivering knowledge management solutions (www.lizherman.com).
She is a senior member of STC and is active in STC’s Eastern Iowa
Chapter and PMI’s Eastern Iowa Chapter. She is already looking
forward to the 2014 STC Summit.
September 2013
C on ve rsati o ns
An Interview with
Owner’s Manual
www.shutterstock.com/3dfoto
Costar Marcus Hunt By Nicky Bleiel | Senior Member
To Watch the interview online, visit www.youtube.com/
watch?v=n9QYknuw52s.
Nicky Bleiel: Welcome to STC Intercom conversations. I’m
Nicky Bleiel and today I’m pleased to be speaking with
Marcus Hunt, costar of Owner’s Manual.
Owner’s Manual, which airs Thursdays at 10:00 PM on
AMC, tests one of the most common divides among men—
those who read the manual and those who do not. Marcus
reads the manuals. His compatriot, Ed Sanders, chooses
not to read them.
Since the members of the Society for Technical Communication write the manuals, we know which approach is
correct. Hi Marcus, thanks for joining me today.
Marcus Hunt: STC are my kind of people. That’s all I have
to say. Team STC all the way.
www.stc.org
NB: Thank you. We’ve been saying “Team Marcus,” so that
works well.
Just to let you know, Marcus, STC’s members write the
manuals and develop the help systems, videos, training
manuals, and more for heavy machinery, aerospace,
software, hardware … you name it. You can see why we’re
interested in your show.
MH: Absolutely.
NB: So far, your challenges on Owner’s Manual have
involved stunt planes, locomotives, dune buggies, and tall
ships, rock quarries—this is a lot of fun stuff— …
MH: It is.
NB: … and logging are coming up in the next few weeks.
Which one was the biggest challenge for you, personally?
9
MH: Whew. I would have to pick two.
I would have to pick the tall ship, which hasn’t aired yet.
It is a 136‑foot, 120‑ton tall ship. For those of you who don’t
know what a “tall ship” is, it’s basically like an old pirate
ship—the old wooden, big pirate ships.
This was one of my childhood dreams and almost an
epic adventure. Basically, it was nighttime, it was windy, we
had hail, we had seas coming over the bow, and we had a
crew of ten. In all the other scenarios, all the other shows,
we were basically responsible for our own doing, and in this
one, we had to command ten people.
They were never put [in danger]—obviously, if we
just said something so stupid or tried to give them a
command that was so stupid, they wouldn’t do it—but
they were asked to do everything we told them to do,
whether it was right or wrong.
Just having to command that many people in those
types of conditions. The crew were all over the boat. That
was, by far, the biggest challenge for me.
The second one would be in Oregon, 21 degrees, the
yarder, crazy logging system, 30,000 pounds of lifting. It
was just so cold the entire time that it’s one of those where
you can barely move for three days straight.
I don’t want to leave him out of this, but it’s also the
product owners as well. Everyone wins.
When did you come to the realization that reading the
manual made your life easier?
NB: Those do sound really, really challenging, and also
with the tall ship, getting that command experience I’m
sure was very interesting.
NB: Well, you definitely have the genes for it. We may have
to recruit you at some point if this acting thing doesn’t work
out for you.
You have a lot of challenges on the show, and they’re
really not for the faint of heart. You’re doing a lot of
dangerous things. You and Ed Sanders work together very
well, although technically you’re supposed to be competing
in this battle of “book smarts” versus “street smarts.”
MH: For your bucket list, though … Bucket list stuff. It was
amazing.
NB: That’s very, very true. Which challenge of all of them
had the best documentation, do you think?
MH: I was a geek as a little kid. Not that people who read
manuals are geeks; I just peg myself out as that guy because
I am that guy.
When I was a little kid, my parents used to buy me little
science kits and little projects to do. I remember taking
something apart and not being able to put it back together
properly, and I pretty much ruined it, because it was pretty
complicated.
What I would do is, I would actually create my own little
manuals. What I would do is take my paper, I would draw
in colors a diagram of what went to where. I’d have my little
parts list, and then when I put it back together, I would be
able to do it no problem.
That kind of stuck with me all the way through. It’s my
personality, and funny enough, I’d probably fit in…. It is
a very patient and meticulous and oriented-to-detail type
work that you guys do. Could I do it? I don’t know, but I
definitely could be an amateur STC‑er.
MH: Right.
MH: [laughs] OK. You know, funnily enough they actually
all had very good documentation, but the best would have
probably been the locomotive.
They actually gave me the original manuals from
the 3100, which was the locomotive that we used; it’s a
275,000‑pound locomotive. Then they gave me no end
of manuals for hand signals, for … you had to know
how many toots to toot when you’re crossing a crossing
where there’s going to be pedestrians or there’s going to
be cars.
If they didn’t have the owner’s manuals for them, I
would try to look it up. I would YouTube it or just go online
and research it. Then again, if I couldn’t find it then, a lot
of the time they would actually give me manuals on set,
and I would read them there.
NB: Well, technical communicators made it happen.
MH: Yeah, they did.
NB: We reduce the liability for you, the user—and I’ll
count Ed in that—we’re going to talk more about Ed later.
10
NB: Was there any time you thought Ed might actually be
in danger because he hadn’t read the manual, or was there
any time you recall thinking you might have been in danger
if you hadn’t?
MH: I like to think of Ed as Herman Munster or the
missing link between ape and man. Just kind of the guy
who goes in there pressing buttons, like [grunts]. The truth
is, he’s a smart guy. We’re both smart enough to appreciate
each other’s opinion, and respect that if he has a better way
to do it, I’m going to listen, and if it’s better I’m going to do
it. The same goes for me.
We had experts on every show, off in the distances,
so were we ever in “I’m going to rip my arms off and
die” danger? No. But was there absolutely real danger?
Yes, there was, in most every episode. The tall ship, as I
said, we had to strap ourselves in and hook in because
we’re sliding all over the decks. Yarder, we had 30,000
pounds of logs hanging from cranes and Ed was down
in the brush.
September 2013
C on ve rsati o ns
NB: You’ll have to look. You creamed Ed both times.
MH: Good.
NB: Not so much on the dune buggy.
Now, how much time do you spend reading the docs to
prep for each episode? You’ve said in other interviews that
you not only read the manuals, you also watch videos.
MH: I do.
Jordin Althaus/AMC
NB: Do you prefer one over the other, or just different
approaches for different things?
Marcus Hunt (right), and Ed Sanders, costars on Owner’s Manual
But to answer your question, probably the airplane for
Ed. While I don’t think it was so much a safety issue of
the plane having an issue, Ed was a bit motion sick so he
blacked out twice, he threw up, and he almost pooed his
pants. Maybe a little more information than you need to
know, but I got a heads‑up on that.
I learned the G straining maneuver, which is very funny
to look at. If you don’t know what it is, it’s the … G‑LOC is
the loss of concentration. It’s where you just kind of black
out like this [demonstrates].
Well, to do it properly you tense up all the muscles in
your body, and you’ve got to take these real short breaths.
It looks stupid, but it’s like [demonstrates]. It looks just that
silly, but what that does is it allows the blood to stay in your
brain so you don’t black out.
Because I read the manual, it made me better off and
less sick, and Ed not so much. To answer your question, I
think that would be a good example of where reading the
manual versus not reading helped me out, being safe.
NB: That would be the example. I, of course, watched all
the episodes and in that episode you cut most of what you
described out …
MH: OK, how long do I spend? I spend quite a bit of time,
actually. For the first two episodes alone I had about 250
pages of manuals that were given to me beforehand, and
then I watched … I probably watched an hour’s worth of
clips on fighter pilots and things like that, which may not
seem like a lot but it’s a lot of information to cram into a
few days.
Do I prefer … when I have to cram a lot of information
that quickly I prefer visual things, especially when it’s
technical data, just because you may know what it says and
you may even know what it is, but when you see it all of a
sudden it snaps like that for me.
I really appreciated, like for the locomotive, getting
to see where all the different pieces were inside that
locomotive in order to start it: all the different buttons,
what switches had to be done, and all the different colors
and the hand signals and stuff like that.
I’m probably visual, 10 to 1.
NB: It makes sense. That’s part of the reason that technical
communicators provide so many different types of
documentation, because people have different preferences.
I’m glad to see that that’s the way you stand on it.
MH: Yeah.
NB: Can’t end an interview without talking about the
zombie apocalypse, for some reason.
MH: Yeah.
MH: [laughs]
NB: … of how sick Ed was, and I would like to say thank
you to your editors for that.
NB: It’s just a very popular topic.
MH: [laughs] Yes. He would, too.
MH: Ed’s stupid zombie apocalypse. Go ahead.
NB: [laughs] I did want to mention, I don’t know if you
noticed this—you probably did—that AMC posts a poll
on their website after every episode, and the question is,
“Whose approach worked better? Ed’s or Marcus’s?” You
won the stunt plane and locomotive polls by a wide margin.
NB: Ed … I don’t know why, maybe it’s all the movies, but
Ed defended his approach—you know, the not reading
the manual approach—in an interview you both did
with Popular Mechanics. His explanation was, “If there
is a zombie apocalypse, no one will have time to read
the manual to figure out what to do.” Therefore, his gut
approach is correct.
MH: Nice. I did not know that, but I’ll have to go look at it.
www.stc.org
11
Now, I’d argue that this is an apples-and-oranges kind of
analogy. I mean, the zombie apocalypse is an event. It’s not
something that needs to be operated correctly.
MH: I pretty much think that everybody on the planet
would argue against Ed’s defense of zombie apocalypse.
I’m actually working on a serum to create zombies so I
can create a zombie apocalypse to prove him wrong.
I don’t even know where he came … he comes up to me
like, “Oh, the zombie apocalypse and the manual….”
That’s the last thing you would be doing. Let’s say you
ran to a plane or something, the first thing you’d do would
be to shut the dang door, lock it, and then I guarantee you
if you don’t know how to start that plane, you’re going to
find a manual or something to figure out how to start that
plane. I don’t even know why he came up with the zombie
apocalypse, but if it happens I guess it’s going to be a good
tell‑tale, which is right.
NB: Yes, and by then we won’t care.
NB: Great, and you appreciate the fact that the …
high-quality manuals, because you’ve obviously been
reading a lot of information that you have found to be
of great quality.
MH: What’s funny is that you read them and you [know]
there are some better than others, and you really
appreciate the well‑written ones, after having to read so
many. You can tell. Some were just kind of, “I’ve got to
make this because it probably needs to be made,” and
then some you could tell that probably the STC‑ers, you
really love what you do[….]
Some may think it’s an absolute boring thing,
but I’m one of those people who I’m very meticulous
and I love to write that stuff down. I’m always the
one to record what I’m doing and make sure that …
I even create manuals; I own an old RV. I created a
fifteen‑page book with pictures and arrows and how to
dump the tanks and how to turn on the generator and
all that stuff. While people are like, “Oh, it’s that guy,”
the second they open it, they are so happy to have it.
MH: You may or may not matter anyway.
NB: That’s right. That’s why people use that argument, I think.
NB: Awesome. Well, we’re definitely going to have to
consider you an honorary member of the Society for
Technical Communication, Marcus.
MH: Yeah.
MH: I’ll take it.
NB: Now, the show’s pretty heavy adrenaline, you have a
danger kind of vibe because there are dangerous things
going on, but at its core it really does confirm that you need
to consult the documentation to do a job correctly and safely.
NB: I really thank you so much for taking the time to talk
to me today. Please tell Ed that even though … I could tell
he’s a really nice guy.
MH: Yes.
MH: He is. He’s a very nice guy.
NB: That’s why you named the show Owner’s Manual, right?
NB: We all think he’s really nice, but the members of STC
are going to keep continuing to root for Team Marcus …
MH: It is, and it’s a … there’s no doubt. You cannot argue
the fact that having a manual is not better than not having a
manual. The show shows that street smarts versus book smarts
… it shows two very different personalities. It shows adventure.
The truth is, every single thing we stepped into this
season, you absolutely have to have a manual to even figure
out how to start it. Maybe not the one where Ed had the
one up on me on the cars. Those you could figure out.
You could sit there and you could flick buttons and
figure it out, but in an airplane and in a locomotive, there
were seven things that you had to do before you could
start that locomotive, and they were 15 feet apart. You were
switching switches inside, having to walk around and on the
other side open doors, prime pumps, press things for it to
glow and then heat up.
There is no way that Ed would figure that out just by
pressing buttons, so I am an absolute true believer in
manuals and I don’t think you can argue that point.
12
MH: I like it.
NB: … in the weeks to come. Have a great day. Thank you
so much.
MH: Nicky, thank you so much and thanks to everybody at
STC for watching. gi
Nicky Bleiel (nickyb@componentone.com) is the lead
information developer for Doc-To-Help (www.doctohelp.com). She
has 19 years of experience in technical communication and in writing
and designing information for software products in the documentation, media, industrial automation, simulation, and pharmaceutical
industries. She’s @nickybleiel on Twitter, and you can see a complete
list of her presentations and articles at www.nickybleiel.com. Nicky
is the president of STC.
September 2013
W r iting and E diting
Do You
Really Want
to Say That?
www.shutterstock.com/antoniomas
Writing in a World of Jargon,
Slang, Corporate Catchphrases,
and Technical Pseudo-Terms
By Harr y C alhoun and Dave Wright
Who among us has not been surrounded by jargon,
slang, corporate catchphrases, and technical pseudo-terms?
But what, exactly, are these elements, and how can we avoid
them when writing for a professional audience?
Most writers and editors probably define jargon as
something similar to what our own coworkers suggested:
“Shortcut language that’s used at work, words and phrases
that are specific to a company or profession but that
shouldn’t be used elsewhere.” Several dictionaries indicate
that this is only one definition, however, and usually not
the first. The first definition of jargon at Merriam-Webster
online, which is typical of other dictionaries, is “confused
unintelligible language.”
If you want to reach a general audience, jargon has
its limitations, obviously, as does slang. And is there a
difference between the two? In “What is Jargon?” on
the Suite 101 website, author Jennifer Silva offers this
definition: “Although functionally similar, jargon and
slang are still quite different. In general, slang is much
more informal and includes street language that would be
www.stc.org
considered unrefined and inappropriate in most professional settings.” Along these lines, a sailboat captain might
use the following jargon, ”When you sheet in after reefing,
check the topping lift,” and a fifteen-year-old might put
sunglasses on a dog and say, “He’s so fly!” In either case,
only the speaker’s peers are likely to understand.
The limitations tied to jargon and slang can likewise
apply to corporate catchphrases. Have you used or heard
anyone say “new news,” “drinking from a fire hose,”
or “spot on”? (Apparently we now have not just news,
but “new news”!) These catchphrases—corporate or
otherwise—remain popular for a time. They might add
color to conversation, but they’re usually poor choices in
our professional writing.
Lastly, a type of technical pseudo-term deserves a
mention. With the rise of computers and the Internet,
we regularly encounter words that seem appropriate but
really aren’t. Instead of using “deinstall,” “demount,” or
“deregister,” for example, we probably want to continue
with uninstall, dismount, and unregister, respectively.
13
The online site NetLingo exists, according to its own claim,
“To track new Internet terms and text and chat acronyms.”
Just going to the “B” section of NetLingo, for instance,
reveals “banana project,” loosely meaning a task so easy a
gorilla could do it, and “ham” to refer to good email—that
is, not spam.
What You Write and Why You Should Write It Well
We all know that our writing reflects our profession and
professionalism. As writers in business and technical
environments, we find ourselves creating a variety of
materials, all of which require precise language. A
marketing writer, for example, must clearly define a
product’s selling features and why it should be purchased.
A technical writer must create instructions that are correct
and concise. Reading poor writing is like listening to music
that’s filled with static—and who enjoys that?
The quality of our writing, however, affects more than
just the immediate target audience. What if your writing
will be translated into other languages? What if people will
search the Internet for your work?
With regard to translation, English slang and other
idiomatic expressions generally fail to translate well into
non-English languages. Consider these examples from
Laura Stampler in the 17 May 2012 issue of the Business
Insider online magazine:
44The Kentucky Fried Chicken slogan “Finger lickin’
good” translated into Chinese as “We’ll eat your fingers
off.”
44The seemingly harmless and cheery Pepsi Cola slogan
“Come alive with Pepsi” apparently translated into
Chinese as “Pepsi brings your ancestors back from the
dead.”
44That lovable symbol of Green Giant vegetables, the Jolly
Green Giant, became the “Intimidating Green Monster”
in Arabic. (“Hey mom, let’s buy some green beans from
the intimidating green monster!”)
44Finally, Coca-Cola, depending on the Chinese dialect,
translates to either “female horse stuffed with wax” or
“bite the wax tadpole.” (“Bartender, I’d like a rum and
bite the wax tadpole, please.”)
While most North American readers understand “hit
the ground running,” a successful translation requires
something closer to the Merriam-Webster dictionary
definition of “to begin or proceed quickly, energetically, or effectively.” The IBM Word Usage database lists
terms such as “deep dive” as among those to avoid in
favor of more descriptive and translatable terms, such as
“in-depth analysis” or “technical review.” It’s also better to
use a simpler form of the word or one devoid of negative
connotations. Hence, “utilize” becomes “use,” for example,
while we should avoid “exploit” altogether because it can be
read, according to Merriam Webster, as using someone or
something “meanly or unfairly for one’s own advantage.”
When writing copy that will be on the Internet, keep
in mind the role of search engine optimization, or SEO.
14
Writing for SEO helps drive search engines to find and cite
a specific website or article. Google’s webmaster guidelines
state: “Create a useful, information-rich website, and write
pages that clearly and accurately describe your content”
(http://support.google.com/webmasters/bin/answer.py?hl=
en&answer=35769). James Mathewson, editor in chief of
ibm.com, emphasizes the value of SEO: “Content quality is
obviously very important for search effectiveness, perhaps
more important than site architecture.”
A Strategy for Good Word Usage
A word usage repository can clarify for everyone in a
company or workgroup what should and should not be
used. And sometimes the benefit extends beyond just better
text. If an item in your company is described by multiple
terms, people reading those terms can easily believe that
they refer to different items. Not helpful or efficient, right?
If you do not already have some type of word usage
repository, it might be time to start one. You can set up your
word usage repository to address any concern—general
consistency, preferred terms, or trademarked items, for
example. Does everyone know the trademark limitations
tied to terms like Kleenex, ZIP, and InstallShield? Does
everyone use a term to reflect a single definition?
Both writers of this article have access to the expertise
of the IBM Style and Word Usage Council, the IBM
Style database, and the IBM Word Usage database, to
Words and Their Usage
The following is a list of categories and terms that
might appear in a word usage repository. Francis
DeRespinis, technical editor and co-lead of the IBM
Style and Word Usage Council, helped compile the list.
Wordy phrasesAlternative
at this point in time at that point in time each and every one of you for the purpose of now
then
each of you
to
Consistency
Use acknowledgment, not acknowledgement
Use schemas, not schemata
General usage
Bufferpool or buffer pool? Use buffer pool.
CRUD. Do not use. Use “create, retrieve, update,
and delete.”
Telnet. Do not use as a verb.
Anticlockwise? Use counterclockwise.
Trademarked items
ZIP®
InstallShield®
September 2013
W r iting and Ed itin g
name a few resources. If you want to create a word usage
repository, the categories discussed here might provide
good starting points. You could include the various terms
mentioned here, perhaps, and then search for websites
that have related information. (In preparing this article,
the authors found a number of relevant Internet sites.)
Once you start developing a usage repository, new and
experienced writers will soon have a ready reference and
everyone will benefit.
A Last Word on Repositories
According to Rita Roque, IBM Storage and Technology
Group terminologist, word usage repositories grow over
time, usually when a word or phrase is submitted by writers
or developers for consideration. A submission is first
examined with regard to its usage in IBM, in the computer
industry, and in general throughout the world. A usage
proposal is then evaluated through stakeholder reviews.
The conversation about terms is ongoing, with some terms
taking far longer to resolve. “Term usage and definitions
can be delineated by product, if necessary, or they can be
defined across a company,” Rita says. “The team works to
avoid using multiple terms for the same thing and multiple
definitions for the same term. In the long run, there’s a
much greater benefit to the customer.”
Here’s to clear writing! gi
The authors are speaking for themselves and not on behalf of
IBM. The information presented here does not necessarily represent
IBM’s positions, strategies, or opinions.
The authors would like to thank Francis DeRespinis, technical
editor and co-lead, IBM Style and Word Usage Council; James
Mathewson, editor in chief of ibm.com; and Rita Roque, IBM
Storage and Technology Group terminologist, for their contributions to this article.
Harry Calhoun (1calhoun@us.ibm.com) is a content
developer in IBM ITSO Global Content Services. His 30-plus years
of writing experience includes work published in magazines such
as Writer’s Digest and Mississippi Arts and Letters and an
award-winning career in marketing. In his IBM career, he has
won several STC awards and has worked on projects ranging from
brochures to email campaigns and Flash presentations.
Dave Wright, PhD, (davidlw@us.ibm.com) is a senior
software engineer and information developer in IBM’s Storage
and Technology Group. He shares responsibility for product user
information across multiple storage products, and has had pieces
in various publications including Northwest Review, American Literary Review, and Quarterly West.
HOPKINS IS
ADVANCING COMMUNICATIONS
Johns Hopkins University offers flexible graduate programs for
communications professionals seeking to advance their careers, and
scholars looking to continue their education.
Master of Arts in Communication
Immerse yourself in an innovative curriculum that integrates digital
technology with strategic communication and strong writing skills.
Location: Washington, DC Campus and Online.
Master of Arts in Writing: Science-Medical Writing
Gain the skills you’ll need as a writer or editor in health, technology,
medicine, nature, space, energy, or other fields.
Location: Online, plus a 7-10 day residency.
Register today
for an on-site or
online Open House
www.stc.org
Learn more:
advanced.jhu.edu/openhouse
15
Style Guides:
Personal and Practical Tips
on How to Get Started
and Keep Going
www.shutterstock.com//Tang Yan Song
By Karina Lehrner-Mayer | Member
This article provides a practical guide to documentation teams for creating documentation guidelines that
are actually used by team members. It helps team leaders
and writers who are still struggling in their day-to-day
work without a formal style guide to think about starting
one. It also includes tips for teams with existing style
guides who would like to increase acceptance and use of
their style guides.
The article is based on my personal experience when I
built and introduced a style guide to a documentation team
of 11 writers and reveals what worked and what didn’t.
16
September 2013
W r iting and Ed itin g
Do You Have a Style Guide?
In the perfect world of a technical writer, every documentation team or publication department has a style guide
that is proudly given to every new writer joining the
team. We all know that this world is not perfect and
when I joined the documentation team in an Austrian
software company almost three years ago, there wasn’t a
department guide to turn to.
The reasons why no writing guidelines were in place
soon became obvious: All of the writers were too busy with
the complex content and the sheer amount of documents
that needed to be updated, written from scratch, and
maintained, some of them in two languages. No one had
the time to do the research such as consulting existing
industry standards that precedes the act of writing a
rule down. And neither did anyone have the nerve or
willingness or patience to write down guidelines.
On my new job, it was clear from the beginning that
among writing tasks one of my responsibilities would be
creating a documentation style guide (during the job
interview I had boldly asked for the team’s style guide).
Although a style guide had never been number one on
the agenda of writers who were struggling with a heavy
work load and faced with complex content and numerous
documents, I was going to build one that would make the
writers happy. (At least that’s how I saw it.)
If you are in a similar position as I was or, as a manager,
wonder if and how to create a style guide, you’ll find helpful
information in this article. And if you already have a style
guide, read on to find out how to keep it alive.
Before You Start
In my experience, two factors are most important for
starting a style guide project: 1) a single person (or, in large
documentation departments, a dedicated style-guide team)
responsible for the project and 2) support of this person’s
style guide activities.
As the style guide supporter, forget all of the historic
reasons for why no style guide exists and stress the benefits
of creating a style guide. Have arguments ready for all of
the things you might hear. For a quick reminder, see the
summary of benefits in the list “Quick reminder: Why every
team should have a style guide” below and learn it by heart.
There can be only one
There must be one (only one) person or dedicated team
that is responsible for the style guide, its content, and
updates. It helps if the style guide team member has
an eye for details and recoils at the inconsistent sight of
user-friendly and user friendly in one document. A neurotic
disposition to have everything done the same way and look
alike and according to rules is also helpful.
Do you read publication style guides in your free time?
If your answer is yes and you are not afraid to enforce a
rule, this may be the perfect task for you. If you tend to
www.stc.org
think of user friendly vs. user-friendly in terms of artistic
freedom, you will probably have a hard time seeing the
need for consistency and convincing others of it.
Bring the manager on board (if they are not
already there) …
It’s vital that the manager and team leaders back up your
style guide activities. This does not mean that they need to
devote time to formulating rules or taking part in lengthy
discussions (because they will have other things to do
anyway) but that they will support your efforts. This means
assigning you the time to research, write, and communicate
style guide rules, as well as standing in when a decision or
more information is needed.
The good thing is, the time needed for style guide
activities will gradually decrease as the style guide grows
and questions are answered. Still, whenever an existing rule
needs to be updated or a new rule must be added, someone
who is responsible should be able to free some time for
these tasks.
… and your co-workers
In general, a documentation style guide helps writers
to concentrate on content and not lose time thinking
about how to spell or format or phrase something. You
cannot stress this enough. Repeat this like a mantra—to
the managers and to the writers. Sometimes writing
conventions may seem time-consuming and irritating, but
in the end the style guide serves only two ends: 1) to help
the company sell more products by increasing user satisfaction and 2) to make the lives of the writers easier.
Getting Started
Look and listen, research, write, communicate
A good starting point to build a style guide from scratch
are existing industry standards (remember, the books you
are reading in your free time), as well as other style guides
you have encountered in other organizations. If there is a
company style guide or another department’s style guide,
take a good look (in my case, there wasn’t one).
When new persons join a team and familiarize
themselves with the products and existing documentation, this is also the perfect time to start the style guide.
There is a certain period when inconsistencies in style and
terminology and other relevant issues stand out. When
the person is not new anymore, they are most likely not
noticing these things anymore or getting used to the way
things are. So, if you are new, get started soon with the style
guide. If not, ask people who have just joined your team or
another department and use their feedback.
Did you notice any inconsistencies in the documents
you have read or taken over? Did you hear any informal
discussions going on the hallway between writers about
how to spell user-friendly? These are also starting points for
your style guide.
17
And, of course, do not forget the rules that are not broken
but complied with and are still noteworthy because they need
to be explained every time a new writer joins the team.
Choose your tool and format
It might seem irrelevant whether you write the style guide
as a Word document or create it with any other tool. On
the other hand, consider the chances you have if you use
exactly the same help authoring or documentation system
that you use for creating your official documents: you can
make the style guide itself an example of a document that
follows the rules. The examples in the style guide will
look just as they should in the official document, and if
something is not working as the rules say (for example, due
to restrictions of the documentation system), you will find
out immediately when you try it out in the style guide.
Researching
Agree with your manager on which industry style guides to
turn to. Do the research alone and present your suggestion
(or, if there are more candidates for a solution, make one
suggestion your favorite one). Have your answers ready for
why you prefer one version over another. There is often no
right or wrong and other factors make the decision, such as
is a rule already followed by the majority of writers, is a rule
accepted by the team, is it easy to follow, etc.
Find your allies
This is not essential, but it can make your life easier. There
might be other writers who share your enthusiasm for rules
and regulations (well, at least a bit). Turn to these teammates
for brief discussions on an issue to be decided. You might
also need their backup if it comes to taking a vote.
Decision-making time
As Krista Van Laan wrote, there is more than one right way
to do things and sometimes it is a matter of taste which way
you go. In a situation where there are two or more equal
solutions, I always like to go with the solution that comes
with the least effort and works best for the writers. Let the
writers and the documents take a vote.
Always involve the team leader and, for sensitive issues,
always involve the manager (for example, terminology issues
regarding product names and branding are usually sensitive).
Communicating
Even as important as writing a style guide rule is making
this rule known to and accepted by all team members. This
is where I had to learn the most to find out what worked
and what did not. It turns out that a combination of written
rules, style guide meetings, short emails, and brief informal
discussions works best.
For introducing the first version of the style guide and
for presenting new or more complex issues, I found a team
meeting with a presentation and discussion appropriate.
18
For minor additions and to brush up on existing rules,
short emails to the team members seem sufficient. I have
made it a habit of sending a style guide newsletter, although
not each week, but I try to keep it fairly regular.
Also, I try to keep all the rules in mind (or at least know
by heart where to find each one) and happily answer any
questions that are directly addressed to me.
If you provide a mix of different means of communication, you increase the chances of reaching each and every
one of your coworkers.
Give examples
What I hear very often from my teammates is that they want
to have each rule illustrated by examples. While the first
version of the style guide did not include examples for all
the rules, I now make a point of providing useful examples
whenever I write a new section in the style guide or send a
style guide newsletter. It seems that the examples get the
most attention.
Keep the Fire Burning
When you start from scratch, you will spend a lot of time
researching and writing and communicating. But as the
style guide grows, you will find that you need less and less
time for your style guide because the important issues have
already been dealt with. Even then, it is essential not to
forget about the style guide altogether.
Even when you have your own workload of documentation to do, keep an eye on the style guide and your ears
open to discussions. Be prepared to devote a certain
amount of time to style guide activities.
Watch out for issues that still come up in discussions
between team members even if they are already solved in
the style guide. These topics are candidates for a quick
reminder, either by email or in a short presentation.
P is for Pragmatic—this is your team’s style guide
I am always open to what goes into our style guide—the
writers decide. Even if a topic is not strictly speaking a
stylistic one, why not include it in the style guide, as it’s better
than to forget about it altogether. Sometimes it turns out that
a topic is first dealt with in the style guide and then deserves
its own place. For example, we had a terminology section
in the style guide that soon outgrew the guide and is now a
separate document. Also, when we began to create instructional videos and tutorials, the video style guide started out
as a chapter in our documentation style guide.
Based on the individual background and makeup of a
team and the specific authoring environments, make this style
guide a special, individual one. For example, we have a fastgrowing, multinational team with writers from all different
kinds of linguistic and educational backgrounds. Although
we write documentation in English, there is only one native
speaker of English on the team. This is why our style guide
also addresses questions of basic English grammar.
September 2013
W r iting and Ed itin g
Some of our documents are translated into and
maintained in German, so our style guide features sections
on German grammar and conventions and all examples in
the style guide are given for English and German.
Stylistic Pitfalls
Keep it short—don’t provide too much
background information
Working with Style
Although you often have to do some research where you
consult various industry style guides and collect detailed
information, be ready to explain the pros and cons of a
specific solution in two sentences.
For example, I had once prepared a detailed four-page
document arguing for a rule to solve a certain problem that
I (and also the other writers) desperately thought needed
to be decided. As it turned out, the manager did not want
to read the paper, but a short meeting where I and the team
leader presented the gist of the four-page document in a
few minutes was sufficient to reach a conclusion.
As disappointing as it sounds for the style-guide writer,
managers and other writers are not interested in the
research details; they only want a quick and professional
solution for their problem.
Keep it small—don’t solve too many topics at once
Break down stylistic areas into smaller chunks. It is much
easier to solve little bits one after the other than a huge set
of rules in one go. (However, don’t forget to keep the bigger
picture in mind.)
For example, we wanted to provide rules for the
structure of our documents. As we have several different
types of documents, from administrator guides to reference
guides to course guides, we started to define the structure
for one document type first, then for the next one, and did
not do them all at once.
Resistance is futile, or is it? Don’t expect that
everyone follows the style guide
Wouldn’t it be nice if everyone happily did as the style
guide says? This is rarely the case in a fast-paced documentation world where every writer must meet tight deadlines,
focus on complex products, and simply forgets about those
rules that mean so much to the person who wrote them.
If you notice that a rule is not being followed and is
clearly explained in the style guide (with a lot of examples),
it is your job to do something about it.
Do the writers not know about the rule? Send a short
email reminder that sums up the rule and gives examples.
REFERENCES AND RECOMMENDED READING
Does the rule require too much effort and time to master
with tight deadlines? Or are there other reasons, such as
restrictions of the documentation system, that make it too
time-consuming for the writer to follow a rule? Consult
with our team leaders and managers on how to address
these issues.
Building style guides is fun and a welcome change to writing
tasks. It is also very rewarding because you can see the
results of your work directly in the documents. The writers,
the documents, and the whole company will benefit from a
documentation style guide that is actually used. So go ahead
and start a brand new one or polish up the old one you have.
Good advice
44Make one person or team responsible.
44For more solutions, present one as your favorite.
44Keep rules simple.
44Be pragmatic.
44Always include examples.
44Communicate in different ways to reach everyone.
Not so good advice
44Try to solve too many issues in one go.
44Present too much information at once.
44Involve too many people in the decision-making process.
44Insert a rule into the style guide and think this is it—the
guide is complete.
Quick reminder: why every team should have
a style guide
44It helps new writers become familiar with the documentation quickly.
44It is a time-saver—writers can concentrate on content.
44It increases the language competence of the team (if
approached by members of other teams on an issue, you
can refer them to the documentation style guide).
44It leads to a more professional look of the documents.
44It increases user satisfaction. gi
KARINA LEHRNER-MAYER (karina.lehrner-mayer@isis
-papyrus.com) holds a degree in translation and has over 15
years’ experience in technical communication. She works as a
technical writer at ISIS Papyrus Europe AG, an Austrian-based
company offering end-to-end solutions for inbound and outbound
business communications. One of these solutions is also used as
authoring system by the documentation team.
Apple, Inc., April 2013. Apple Style Guide. https://help.apple.com/asg/mac/2013/ASG_2013.pdf.
IBM Press, 2004. Developing Quality Technical Information. A Handbook for Writers and Editors. 2d
Ed. Upper Saddle River, NJ: Prentice Hall.
IBM Press, 2012. The IBM Style Guide. Conventions for Writers and Editors. Upper Saddle River, NJ.
Microsoft Corporation, 2012. Microsoft Manual of Style. 4th Ed. Redmont, WA: Microsoft Press.
Microsoft Corporation, February 2008. Microsoft German Style Guide. Public Version 1.0. www.microsoft.com/Language/en-US/StyleGuides.aspx.
Sun Technical Publications, 2003. Read Me First: A Style Guide for the Computer Industry. 2d Ed. Upper Saddle River, NJ: SunSoft Press/Prentice Hall.
Van Laan, Krista, 2012. The Insider’s Guide to Technical Writing. Laguna Hills, CA: XML Press.
www.stc.org
19
www.shutterstock.com/ 3Dmask
Lessons Learned
in Marketing
Communication
Over Barbecue
By Kevin Cuddihy
One July day, I woke up to an inviting offer in my email.
Famous Dave’s, the barbecue chain restaurant, sent me a
special offer: “Today only” I could get 20 percent off the
entire check for lunch or dinner!
Awesome!
I came into work and persuaded a coworker to join me
at the nearest Famous Dave’s, and we saved 20 percent
on our lunches. What a deal! Then came the next day. I
received another email from Famous Dave’s with another
special offer. The day after that came one more. And again.
And again. Every day, a new “one-day” deal for saving at
Famous Dave’s. That “special” offer didn’t seem so special
anymore. In one short week, I got emails with the following
subject lines:
4420% off adds up to big savings
44Get through hump day with a deal on BBQ
44Kevin, act fast! This offer is valid today only
44$10 off $30 today. Or, you could pay full price
somewhere else. You choose.
44Save some bones on your BBQ today
44Sunday Special: 20% off
And they haven’t stopped. I don’t know why Famous Dave’s
all of a sudden started sending emails every day (they’d had
my email address for months), but send them they have.
However, it’s had an unintended effect.
The first time I received the email caused a positive
reaction: I went to the restaurant when I wasn’t already
planning on doing so. They offered me what I interpreted as
something special and I took them up on that offer. But the
20
repeated emails—a different email every day, and often the
same offer over and over again—has prompted a completely
different reaction. Now I no longer look forward to these
emails as a reason to have lunch at Famous Dave’s. Instead,
I know that the next time I want to have lunch at Famous
Dave’s, there will be a coupon waiting for me in my inbox.
The difference is subtle but important. In the first
instance, they’re getting me into the restaurant when I
wasn’t otherwise planning on eating there. They’re creating
an “event” for me. In the second, however—what this overexposure has done—is simply cost them money. I’m not
visiting the restaurant more, but rather the times I do visit
(and I was a somewhat regular customer already), they’re
actually costing themselves money. I’m not visiting the
restaurant any more often but I am spending less when I do
go thanks to these coupons.
Contrast Famous Dave’s with another of my favorite
chain restaurants, The Buffalo Wing Factory. I get perhaps
four or five emails from them every year. When I see an
email from BWF in my inbox, I know something special
is going on. A Super Bowl special. New Monday night
football hours. A holiday sale. But only four or five emails
a year seems low. There’s a wide gap between “daily” and
“quarterly” in terms of emails received that they will get
more of my business.
Contrast these marketing emails also with “flash sales”
that a number of companies (including STC) have done
recently. A flash sale is usually online-only and over a
specific time period: 4 hours, 12 hours, or one day. Hold
September 2013
W r iting and Ed itin g
these “flash sales” too often, however, and you’re not
gaining customers so much as losing money that they likely
already would have spent. As with me and Famous Dave’s,
instead of seeing a flash sale and acting when they might
not have otherwise, they’re waiting for the inevitable sale
email and buying items they already wanted but at a steep
discount. Space them out right, and they’re a lure to bring
the fish in fast and furious.
The communications department at STC is the
“gatekeeper” of outgoing emails, and we’re constantly
trying to walk a fine line between informing STC members
about benefits and offerings, and annoying them with too
much email. We look for ways to combine messages, to
provide information on multiple events or opportunities
in one email. We’ve introduced sidebars to most of our
emails to remind members about other events rather than
sending another full “reminder” email. And we’ve used our
e-newsletter, TechComm Today, and social media outlets to
share multiple messages together as well.
Still, we’re aware that there are some weeks that—like
Famous Dave’s—we might send an email a day. However,
we try very hard to make sure that we have something
important to say and that the topics, methods, and layouts
of our communications are different. Recall the list of
subject lines from Famous Dave’s emails; they all were
essentially saying “save on BBQ.” Contrast that with a recent
week of STC subject lines:
44STC Members Receive Special Discount to AMWA’s 73rd
Annual Conference
44Visualize an Engaging Customer Experience with this
STC Webinar
44Great savings start with great tools. #douwriteright?
44The Latest Issue of Intercom is Online
44Introducing the STC Tryout recruitment campaign
In this collection of emails, we sent out several different
messages—an offer from one of our partner organizations,
information on a webinar, product details from one of our
corporate partners, the publication of Intercom, and the
announcement of a short-term “member-get-a-member”
campaign. The messages are completely different and offer
something new each time. While our emails are not always
that varied, we make an effort to space out education emails,
to not send membership renewal emails too often, and to
keep information about the Summit to once a week or less.
We also try to include a different header image for each
type of email to differentiate them. So while the amount of
overall email is high, the topics aren’t repetitive and the view
isn’t always the same. (And we like to think it’s just evidence
of everything you get by being an STC member!)
We also keep an eye on what’s probably the biggest debate
in email marketing: what days and times are best for sending
emails? Doing a Google search for “best day for email
marketing” finds articles with the following conclusions as
to the best day: Thursday. Midweek. Weekends. Tuesday and
Thursday. Friday. Sunday. The only thing the studies agree
upon is that Garfield had it right: I hate Mondays.
www.stc.org
Time has the same variety. One article claimed “early
morning email delivery has the lowest open rates.” Another
said “post-work peak” is the best time. Still another, “email
opens increased after noon.” Want another suggestion? Try
8:00–10:00 AM. Or how about “middle of the day, usually
11:00 AM–2:00 PM.”
Suffice to say, if you want to justify a specific day and/
or a specific time to send an email, you can find a study
to back whatever you want to do. But for all the studies
conducted, the only thing that matters to you is when your
emails are best received. If you’re using a service such as
Constant Contact or MailChimp, take full advantage of
their reports. Compare and contrast various emails on
various days. MailChimp has an option to download all
reports into one Excel spreadsheet, with day of week and
time of day included along with the important information
on opens, clicks, and opt-outs.
It’s very easy to become familiar with the reporting
structures of the two sites, and once you’re familiar it’s also
very easy to see at a quick glance when a particular email or
subject isn’t well received. In the past, we’ve changed course
in a planned month-long membership campaign thanks
to reviewing the numbers, and we’ve adjusted subject lines
based on what’s succeeded and what hasn’t (with both A/B
testing and simply reviewing open rates of similar emails
with different subjects).
One thing we’ve tried recently is to send similar emails
on the same day of the week; during membership season we
sent most of our membership emails on Thursdays. When
we were publicizing the Summit, most of those emails went
on Tuesdays. Especially with sending multiple emails per
week, it’s a way to help recipients know when to look for the
specific material—either out of interest or in order to ignore
it. While members ignoring STC emails is obviously not
ideal, it’s greatly preferable to the alternative of opting out
of all emails from us. But if Joe Member gets an STC email
on Tuesday, he knows without even seeing the subject line or
the topic-specific header that it’s about the Summit. If he’s
interested in that information, he can read. And if not, it’s
a simple click of the delete button. Not everyone is going to
be interested in every email we send, but we want them to be
able to easily and quickly determine if they are interested.
Overall, email marketing communication is still a very
fluid and subjective science. The best day is debatable. The
best time is debatable. The key phrase “for you” (or “for
your company”) should be your biggest concern. See what
works for you, what works for your customers (or members,
in our case), and adapt. gi
Kevin Cuddihy (kevin.cuddihy@stc.org) is media manager
at STC and assistant editor for Intercom. He coordinates or assists
with email communications for STC, his homeowners association,
and UMPS CARE Charities, the official charity of Major League
Baseball umpires. He’s the coauthor of the trivia book Christmas’s
Most Wanted: The Top 10 Book of Kris Kringles, Merry
Jingles, and Holiday Cheer.
21
SOCIETY PAGES
The 2012–2013 Salary Database Is Now
Available for Download and Purchase
The 2012–2013 Salary Database
is now available for download. All
members receive a free copy of the
Salary Database PDF, which includes
charts, maps, and an evaluation by
STC’s economist, and nonmembers
may purchase the publication for
$49. Visit www.stc.org/publications/
products/salary-database for full details
(and see infographic on page 23 for
a sneak peek of the results).
The STC Salary Database is a
tool that can be used to conduct
more powerful job searches, make
a strong case for a raise, or prepare
department payroll budgets. The
data in the Salary Database are drawn
from the United States Bureau of
Labor Statistics’ (BLS) Occupational
Employment Statistics (OES), the
main resource of human resource
departments across the United States.
Use the STC Salary Database
if You Are:
44An employee looking for solid
facts to back up a raise request
44A manager seeking salary figures
to assist with setting budgets or
bidding for projects
44A freelancer investigating average
hourly fees for a different industry
or city
44A job-seeker needing insight
on what industries and what
geographic areas hold the most
new jobs
44A global technical communicator
looking for rates to charge or pay
for a project or consultant in the
United States
44Any technical communicator in
need of either annual or hourly
wage information
2014 Membership
Season Now Open
The 2014 STC membership season
opened on 16 September! Renew
your membership today and enjoy
the benefits that make you a better
technical communicator.
There are a few new things in
2014 that make membership even
move valuable:
1. The SIG Value and Gold Education
membership levels have been
combined and become the Gold
Value Package membership, with
dues of $425 for the year. This
option takes the previous Gold
Education level and adds the option
of membership in all STC Special
22
Interest Groups—without raising
the price! Gold members will be
able to select membership in any
and all desired SIGs now when they
renew or join at this level. Gold
membership still includes: one
chapter, five free Web seminars, and
half off of one online course.
2. All Student memberships now
include membership in the
Academic SIG.
3. The limited-time Early Renewal
Discount is for renewing members
only. Only 2013 members will be
able to save $30 on dues during the
early renewal period. This brings
This year’s data offers new insights
into how the emerging recovery has
and will continue to influence the
demand for technical writers. The
most dramatic story is the growing
importance of export markets to the
U.S. economy, but the Database also
shows a shift from traditionally large
markets for technical writers both
regionally and by industry. The new
sections for 2012–2013 highlight the
largest and fastest-growing industries
and geographic areas in terms of both
wage growth and job growth.
Members can also purchase the
data in Excel spreadsheets to format,
analyze, and manipulate the data easily.
Visit www.stc.org/publications/products/
salary-database for more information on
the Salary Database, to purchase Excel
spreadsheets, and to download the
publication at any time. gi
a Classic membership down from
$225 to $195, but you must renew
early to get this discount!
And, of course, all memberships
continue to receive the same great
benefits you’ve come to expect from
STC—online subscriptions to the
award-winning Intercom and Technical
Communication; access to the Salary
Database; our library of over 140
free, on-demand, archived seminars;
discounts from HP, LifeLock, Hyatt,
MadCap, Lenovo, ComponentOne,
and others with our Affinity Program;
significant price reductions on STC
webinars, online courses, recorded
sessions, and the annual Summit; a
14-day advance viewing on all jobs
posted to the Job Bank; and networking
opportunities across the globe.
So renew your STC membership
today and be a part of your Society.
Visit www.stc.org/membership/ for more
information or email membership@
stc.org with any questions. We look
forward to a great 2014! gi
September 2013
Technical communicaTion Jobs
Reminder of Deadlines
for Awards and Honors
Top Ten areas
for Tech Comm Jobs
1
2
3
4
5
6
7
8
9
10
Washington-ArlingtonAlexandria, DC-VA-MD-WV
New York-Northern New JerseyLong Island, NY-NJ-PA
Boston-Cambridge-Quincy, MA-NH
Los Angeles-Long Beach-Santa Ana, CA
Seattle-Tacoma-Bellevue, WA
Dallas-Fort Worth-Arlington, TX
San Francisco-Oakland-Fremont, CA
Philadelphia-CamdenWilmington, PA-NJ-DE-MD
Chicago-Joliet-Naperville, IL-IN-WI
Detroit-Warren-Livonia, MI
Top Ten industries with the largest
Technical Communication Job Gains
20% Architectural, Engineering,
and Related Services
Employment Services 14%
12% Other
Have You Seen STC’s
Notebook Lately?
9% Engineering Services
9% Wholesale Electronic Markets
and Agents and Brokers
11% Testing Laboratories
Other Information Services 12%
Management, Scientific, and Technical Consulting 13%
Salary ranges for Technical Writers in the Ten largest MSas
Metropolitan
StatiStical area (MSa)
annual
Wage range
Washington-ArlingtonAlexandria, DC-VA-MD-WV
Metropolitan Division
55K–93K
New York-White Plains-Wayne,
NY-NJ Metropolitan Division
48K–93K
Boston-Cambridge-Quincy,
MA NECTA Division
Metropolitan
StatiStical area (MSa)
annual
Wage range
Dallas-Plano-Irving, TX
Metropolitan Division
49K–77K
Los AngelesLong Beach-Glendale,
CA Metropolitan Division
62K–90K
61K–99K
San Diego-CarlsbadSan Marcos, CA
60K–86K
Seattle-Bellevue-Everett,
WA Metropolitan Division
73K–105K
Minneapolis-St. PaulBloomington, MN-WI
50K–77K
San Jose-SunnyvaleSanta Clara, CA
77K–115K
Denver-AuroraBroomfield, CO
50K–76K
www.stc.org
The deadlines for nominations
for many of STC’s awards and
honors are upcoming. Please see the
STC website, www.stc.org, for more
information or to find out how to
nominate someone.
44Associate Fellow
Recommendations: 15 October
44Fellow Nominations: 15 October
44Sigma Tau Chi and Alpha Sigma
Honors Societies: 26 October
44Jay R. Gould Award for
Excellence in Teaching Technical
Communication: 2 November
44Ken Rainey Award for Excellence
in Research: 2 November
44Distinguished Community Service
Awards: 2 November
44Community Achievement Awards:
21 January 2014
44Community Pacesetter Awards:
25 March 2014 gi
The annual Salary Database is a benefit of membership. Join Today!
To learn more, visit www.STC.org
STC’s Notebook is the official
blog of the Society for Technical
Communication, with news,
announcements, marketing, and
more. It’s often the first place new
information is released and the best
way to stay up to date on your Society.
Starting earlier this year, it’s also
a great way to stay up to date on
technical communication as well!
We’ve introduced a number of guest
bloggers to STC’s Notebook, on topics
such as business matters, freelancing,
publishing, usability, design, editing,
tech comm in the UK, and more.
We’ve even invited a few of our
sponsors to blog with special offers
and invitations.
Visit http://notebook.stc.org and see
for yourself—then bookmark it and
visit regularly, or sign up for our RSS
feed to get every post delivered to
your email inbox. gi
23
SOCIETY PAGES
Intercom’s 2014 Editorial Calendar
For more information on these themes or writing for Intercom, visit
http://intercom.stc.org/write-for-intercom.
January 2014—Personal Productivity:
Work Smarter, Not Harder
Submissions due: 11/1/2013
Ads due: 11/15/2013
February 2014—Plain Language
and Information Design: Case Studies
Guest Editor Karen Schriver
Submissions due: 12/1/2013
Ads due: 12/15/2013
March 2014—Career Planning:
Transitioning, Cross-Functional Roles,
Professional Development and Education,
Social Networking and Job Hunting
Submissions due: 1/1/2014
Ads due: 1/15/2014
April 2014—The Bleeding Edge:
Emerging Trends and Technologies
Guest Editor Neil Perlin
Submissions due: 2/1/2014
Ads due: 2/15/2014
May 2014—Content Is a
Business Asset: Content Marketing,
Branding, Metrics, Value
Guest Editor Jack Molisani
Submissions due: 3/1/2014
Ads due: 3/15/2014
June 2014—The Art of Professional Writing:
Technical Writing and Rhetoric, Writing
for Industry, Manufacturing Writing,
Medical Writing, Policies and Procedures
Submissions due: 4/1/2014
Ads due: 4/15/2014
STC Communities and
Staff Win APEX Awards
Four STC communities and
members of the STC staff recently
were named winners in APEX
2013, the 25th Annual Awards for
Publication Excellence. APEX Awards
are based on excellence in graphic
design, editorial content, and the
ability to achieve overall communication excellence. APEX Grand Awards
honor the outstanding works in each
main category, while APEX Awards
of Excellence recognize exceptional
entries in each of the individual
categories. Of the thousands of
entries, just 100 won APEX Grand
Awards. Congratulations to the
following STC winners:
44STC Carolina Chapter: APEX
Award of Excellence in the
category of Newsletters—
Electronic and Web
24
44STC Chicago Chapter: APEX
Award of Excellence in the
category of Newsletters—
Electronic and Web
44STC New York Metro Chapter:
APEX Award of Excellence in the
category of Newsletters—E-Mail
44STC Technical Editing SIG:
APEX Award of Excellence in the
category of One-to-Two Person–
Produced Websites
44Elizabeth Pohland and Intercom:
APEX Award of Excellence in the
category of Magazine and Journal
Writing
44The 2011–2012 STC Salary
Database, written and compiled
by Rick O’Sullivan: APEX Award
of Excellence in the category of
One-of-a-Kind—Custom Published
Publications
July/August 2014—Content Strategy:
Converting Legacy Content, Conducting
a Content Analysis
Submissions due: 5/1/2014
Ads due: 5/15/2014
September 2014—API Documentation
Guest Editor Tom Johnson
Submissions due: 7/1/2014
Ads due: 7/15/2014
October 2014—Rescue Me!
How to Rescue Troubled Technical
Communication Projects and Teams
Submissions due: 8/1/2014
Ads due: 8/15/2014
November/December 2014—
Agile Technical Communication:
Using Methodology from Agile Software
Development for Agile Technical
Documentation and Agile Teams
Submissions due: 10/1/2014
Ads due: 10/15/2014
44And last but not least, STC.org and
Webmaster Kobla Fiagbedzi: APEX
Grand Award in the category of
Websites—Nonprofit Small Office
The APEX judges said of the
STC website: “Just an exceptionally
well-prepared, cutting-edge website
that offers an appealing design,
functional layout and navigation, and
extensive, valuable editorial content.
It’s definitely worth bookmarking if
you are a technical communicator—
or even if your interest in the field is
more general. It’s a professional site
for a professional audience.”
Congratulations to all the winners,
especially Kobla for the APEX Grand
Award!
For more information on the
APEX Awards and a full listing of
winners, visit www.apexawards.com. gi
September 2013
The Strategic IA
Play to Your Strengths,
www.shutterstock.com/ollyy
Shore Up Your Weaknesses:
The Dynamic Duo of Project Manager
and Strategic Information Architect
By Andrea Ames | Fellow and
Alyson Riley | Senior Member
In our roles as strategic
information architects (IAs), we’ve
both had some exceptional partnerships with project managers working
on product content teams. We decided
to explore the essence of those
experiences to provide some insights
and practical advice for IAs and project
managers on a professional relationship that is seldom explored: that of
the IA and the project manager.
We’re huge fans of Tom Rath’s
book StrengthsFinder 2.0. We use
this tool
frequently to
communicate
with others
about who we
are, what we
do, and what
we don’t do;
to understand
the unique
gifts of our
colleagues; to
This column explores
maximize the
the strategic aspects of
capabilities
information architecture and
of our teams;
the tools to equip information
and to ensure
architects (IAs) for success.
that we stay
Topics will address
the business, strategy,
focused on
user experience, and
work that
implementation of strategic
plays to our
information architecture,
strengths.
including organizational,
We’d like
content management, and
tactical considerations. Send
to use the
your comments, questions,
StrengthsFinder
and suggestions for future
framework
articles to thestrategicia@
here to discuss
pobox.com.
www.stc.org
why effective partnerships between
project managers and strategic IAs
are so important to the success of
teams and projects.
Let’s begin by taking a look at
some very specific StrengthsFinder
strengths. In addition to what you
can find in StrengthsFinder resources
in print and online, Rachel DuBois
contributes an interesting classification
scheme that will help in our analysis.
DuBois groups the strengths into
four categories: “strategic thinking,
relationship building, influencing,
and executing strengths, (although
we prefer the term delivery to execution,
sensitive as we are to implications).
Here’s what we look like from a
StrengthsFinder 2.0 + DuBois perspective
(plus a quick-and-dirty description for
each strength, for those of you who are
new to this stuff):
44For both of us:
66Strategic thinking—Strategic:
You “see patterns where others
only see complexity.”
66Strategic thinking—Ideation:
“You are fascinated by ideas …
always looking for connections
… [and] new perspective on
familiar challenges.”
66Influencing—Activator: You
believe that “Only action can
make things happen.”
44For Alyson:
66Strategic thinking—Input:
“The world is exciting precisely
because of its infinite variety
and complexity.”
66Influencing—Maximizer:
“Excellence, not average, is your
measure.”
44For Andrea:
66Strategic thinking—Futuristic:
You “see in detail what the
future might hold, and this
detailed picture keeps pulling
you forward, into tomorrow.”
66Influencing—Command: You
“take charge … take a stance
and ask [people] to move in a
certain direction.”
As you can see, DuBois classifies
most of our strengths as strategicthinking strengths, although we each
have strengths that she classifies as
influencing strengths. Our top five
strengths are very different from
those you would typically see in those
focused on execution (or delivery).
For DuBois, execution-related
strengths tend to include things like:
44Arranger: “You are a conductor
… you enjoy managing all of the
variables, aligning and realigning
them until you are sure you
have arranged them in the most
productive configuration possible.”
44Consistency: “Balance is important
to you.… people function best in
an environment where the rules
are clear and … where people
know what is expected.”
44Deliberative: “You like to plan
ahead so you can anticipate what
might go wrong.”
44Responsibility: “When assigning
new responsibilities, people look
to you because they know it will get
done.”
44Discipline: “Your world needs to
be … ordered and planned. So you
instinctively improve structure on
your world.”
25
The Strategic IA
44Focus: Goals “serve as your
compass, helping you determine
priorities and make the necessary
corrections to get back on course.”
Don’t those things all sound like the
strengths of a great project manager?
And does it come as any surprise that
those are not our top strengths? And
where are we going with all of this?
We know that not every strategic
IA looks exactly like us from a
StrengthsFinder perspective, but we’re
guessing we have some things in
common—namely, that we’re stronger
in the vision stuff but weaker on the
management stuff. One of the big
ideas from StrengthsFinder 2.0—and the
heart of our message in this column—
is that “You cannot be anything you
want to be—but you can be a lot more
of who you already are” (page 9). We’ve
been around long enough to realize
that we’re happiest being who we are—
and we’re not happy when we’re trying
to be project managers. StrengthsFinder
2.0 is built on the idea that people are
most happy and do their best work
when they are doing things that align
with their core strengths. Execution is
not our core strength. On the contrary,
we work best when we acknowledge
that fact and shore up our weaknesses
by pairing with people for whom
execution is a core strength—the
people who are happiest doing project
management things and not doing the
kind of stuff that we do.
Beautiful things happen when
a strong, strategic IA pairs with a
strong, execution-focused project
manager. But don’t just take our word
for it. We sat down with a handful of
excellent IBM project managers—
Colleen Enright, Katherine
McMurtrey, and Tim Hogan—to talk
about the good things that happen
when we play to our strengths and
shore up our weaknesses with strong
IA and project management collaboration. Here’s what we discovered
while reflecting together on successful
IA-PM partnerships.
Project Managers Need IAs
Our colleagues in project
management told us that IAs
26
provide tremendous value to them
and the projects they manage by
ensuring that they and their teams
stay focused on the highest value,
highest priority areas of work. “As a
project manager, you want to make
sure that your team is working on the
highest value content,” they told us.
“Resources are limited and you can’t
do everything.” Given this reality, the
project managers observed that “the
IA has knowledge about high value
content” that the project manager can
leverage in order to “move resources
around and put the eggs in the right
basket.” The project manager and
the IA share the common goal of
wanting “the best content possible for
our users,” and the IA helps provide
the big picture sense of strategic
priorities. One project manager
said, “Oftentimes, I’m so deep in the
details—I’m looking at [our project
management tools] and making sure
that the team isn’t overburdened.…
it’s difficult to pull out and look at
things at a high level.” Others echoed
this theme, noting that “I also don’t
have the time—I know I should make
the time, but I can’t invent time!—to
see what other teams are doing. Am
I consistent with everyone else?”
IAs strengthen project managers
by providing insight into strategic
content best practices across teams
and projects along with a higher-level
view of client needs and the overall
content architecture.
And this collaborative process
can lighten the load. One project
manager noted, “When you’re
collaborating with someone who has
a different perspective, it makes work
more fun and interesting—we’re
learning from each other all the time.
We’re coming at the same problem
with a different approach.” The rest
of the group agreed: the “synergistic
division of labor made us enjoy
our jobs more.” In other words, “I
hate [doing] this but I like [doing]
that—and vice versa. What we like
doing is in balance with our strengths
and the likes or strengths of the
other person.” (A little StrengthsFinder
philosophy in action!)
IAs Need Project Managers
It should be no secret from our
introduction that as strategic IAs we
are highly dependent on an effective,
symbiotic relationship with strong
project managers. In our conversation, we defined strong project
managers as those who excel at classic
project management thinking and
activities, but who do so strategically,
thinking about work that matters
relative to the end goal and ensuring
that the right work gets the right
focus. From an IA perspective, it’s
extremely important that project
managers “get it.” “They don’t have
to do [information architecture],”
said one of our interviewees, “but
they have to understand it enough
so that they can make decisions and
prioritize things at a [more granular
level of detail].” Effective project
managers make good decisions about
allocating and managing resources
based on a strong understanding of
strategy. They prioritize work based
on a shared understanding of the
big picture. This is crucial to IA
success: a vision without an effective
implementation plan is worthless (In
true Activator style, Alyson has a sign
hanging over her desk that says, “Ideas
become real at the point of action.”)
Project managers support IAs
(and their teams in general) by
ensuring that strategy items make
it into a plan and are assigned
appropriate resources. We cannot
overemphasize the importance of
project management in managing
“the plan”—their strong roots in
the “here and now” and their savvy
management of what it takes to
achieve a vision are critical. Project
managers also are critical in making
sure that schedules allow enough
time for IAs to bring the team into
the conversation by planning and
delivering education and evangelism
prior to winning the team’s
acceptance of the strategy (more on
this topic in the next section).
IAs also need the support of project
managers to ensure that the team
that must implement the information
architecture understands and buys
September 2013
into the strategic vision. “More than
one person backing up the direction
is helpful from a team management
perspective,” our project managers
told us. “It’s mutual reinforcement.”
Often the PM goes beyond mutual
reinforcement to actually helping the
IA “sell” the vision more broadly to
the team. For example, there are times
when a strategic IA will propose a new
vision that is very aggressive or involves
something different from what has
been done in the past. It is natural for
some team members to think that it’s
impossible to “get there from here,” to
face such a proposition with concern
or even fear. In those instances, a
strong project manager will strengthen
the IA’s vision by showing how it is
indeed possible to get there from
here. A good project manager who
understands the vision can help calm
fears and bring the discussion down to
an implementation level that provides
a degree of comfort to the team while
addressing critical “doability” issues.
This way the strategic IA can stay “in
the clouds” and incite enthusiasm for
a better vision for tomorrow, while the
PM can be the balancing influence
that ensures a strong implementation
plan and instills comfort in (and
thus buy-in from) the implementation team. The project managers we
spoke with backed up this idea, citing
instances such as “when you’re new
to writing or new to a team, and you
don’t trust the direction that someone
is telling you to go—having both an
IA and a [project manager] telling
you that this is the direction, the right
direction, and the reasons [behind
it]” is highly effective. IAs and project
managers can work together to tell
the story behind the strategic vision;
given their unique strengths, each will
tell the story in a unique way, focusing
on different aspects, and in so doing,
win team support. The vision becomes
a plan with the collaboration of the
IA and project manager working
together.
What IAs Should Know
About Collaborating with
Project Managers
When we asked our project managers
about what IAs could do to better
work with them, the response we got
was both quick and loud. “The IA has
to be able to sell it!” they said. In other
words: “Give me the information I
need, but do it with such confidence
that I am convinced it’s the way to
go. If I struggle with it, then I have
a hard time convincing others that
it’s the way to go. This is a skill set
and an action. Be able to articulate a
future vision well!” Others continued
with this thread: “Show the passion
and value—get others signed up and
excited.” This means not “OK, now
I have this plan and I need some
resource to do it.” On the contrary,
this means that the IA should envision
their strategy work as “a collaborative
process … team building and selling
a vision.” Our project managers
encouraged IAs to “treat people the
right way” by bringing them along
on the strategy journey, involving
them in the data gathering, learning,
synthesis, and ideation that is core
to our work as IAs. The project
managers asked for “true collaboration, not a handing-down-of-an-edict.”
This means “building trust—building
friendship—where learning
can happen. Then you get more
comfortable going into new places
because you’re doing it with someone
you trust.” One of the best ways that
IAs can achieve this goal is to involve
their project managers early on in the
strategy and design process.
Take-Aways
For the project manager: We know you
don’t like the strategy stuff (the project
managers we talked to actually used
the word “hate”)—but work with your
IA to understand it. If your IA isn’t
doing a good job selling the strategy,
say so. Hold the IA accountable for an
effective communication plan and for
driving the vision and culture of the
team. Sign up to support the IA by
actively selling the vision.
For the IA: Avoid the temptation
to throw your strategy over the wall
and move on to the next project. Yes,
you need to be focused on the future
while your implementation team is
focused on today’s delivery—but you
need to bring the team along with you.
Start to look at the hearts and minds
of your team as a deliverable. Gauge
your success by how well your team
members can explain the strategy,
how they fit into the big picture, and
why their work is important. You
know you’re doing a good job when
your team members are passionate
about the strategic value of their
work and can articulate it in ways that
resonate with those outside your team.
Leverage your project manager in this
process and encourage open, honest
feedback about your work, communication, and leadership.
For all of us: The oracle at Delphi
gave us some advice somewhere
between the 6th and 4th centuries
BC, and the ancient Greeks thought it
was important enough to carve it into
the stone of Apollo’s temple. “Know
thyself”—once a wise and novel idea,
and now a cliché. In his StrengthsFinder
2.0 book, Rath quotes Peter Drucker
who said, “Most people think they know
what they are good at. They are usually
wrong.” Maybe we ought to revisit
that ancient Greek cliché and find in
it very freeing advice for those of us
harried by the pace of the modern
world. Figure out your strengths and
focus your energies there. Be free to
be who you are, and be confident and
comfortable with who you’re not. Go be
you and build partnerships with people
who aren’t you. Value what you don’t
have and be intentional about finding
smart, fun people to help fill in your
gaps. And consider taking the StrengthsFinder test—how often is the answer to
one of life’s significant questions “go
take an online quiz”? gi
DuBois, Rachel. Strengthsfinder’s 4 Categories of Strengths: A Creative Reworking. The Touchwood Project. www.touchwoodproject.com/
strengthsfinder-4-categories/.
Rath, Tom, 2007. StrengthsFinder 2.0. Gallup.
References
www.stc.org
27
Advancing Your Career
Advancing Your Career through
Progressive Information Disclosure
www.shutterstock.com/ newart
By Jack Molisani | Fellow
I had a fundamental, careerchanging realization that I’d like to
share with you. But first, a question:
What do the following have in
common?
44TV or radio news
44Press releases
44Procedural documentation
44Job interviews
Answer: Progressive information
disclosure (or lack thereof).
What is Progressive
Information Disclosure?
I have been doing progressive
information disclosure most of my
writing career, and newspaper editors
have been doing it since the invention
of paper.
So what is progressive information
disclosure (PID)?
Wikipedia states that “progressive
disclosure” is an interaction design
28
technique that sequences information
and actions across several screens
in order to reduce feelings of
being overwhelmed for the user
(http://en.wikipedia.org/wiki/Progressive_
disclosure). In its most formal definition,
progressive disclosure means to move
complex and less frequently used
options out of the main user interface
and into secondary screens.
In a LavaCon conference session
titled “When Worlds Collide:
Improving the User Experience by
Applying Progressive Information
Disclosure,” Andrea Ames offers that
progressive information disclosure:
44Enables you to provide the right
information in the right place at
the right time
44Defers display of novice
information, background
information, concepts, etc., until
the user needs and requests it
44Reduces complexity by revealing
only the essentials for a current
task, and then reveals more
information as users advance
(To find Ames’s session slides,
search Google or Slideshare.net for
“Andrea Ames #LavaCon.”)
In printed media, newspapers
support this brilliantly. So do wellwritten press releases:
1. You skim the headlines to find a
topic of interest.
2. You read the first sentence to
get the essence of what is being
communicated.
3. You can continue reading the
first paragraph or two for more
information.
4. Then, if you are interested, you
continue reading the rest of the
piece.
I believe procedural documentation
can be equally
brilliant. For
example:
1. Chapter titles
introduce the
subject of that
chapter.
2. Multi-level
headings
(Heading 1,
This column addresses
Heading 2,
job hunting and career
etc.) subdivide advancement, focusing
topics.
on various aspects of
career growth. It’s written
3. Numbered
steps give you from the perspective of
the procedure. someone who has been a
technical writer, technical
4. Then, if you
communication manager,
need more
and recruiter, and who
help, you can worked as a captive (fullread sub-steps: time) employee and an
1a, 1b, 1c, etc. independent contractor
before finally starting his
Let’s take this
own company. If you have
concept a step
questions or suggestions
further and apply for a future column,
email them to jack@
it to writing for
prospringstaffing.com
online media.
with “Career Question”
in the Subject line.
September 2013
PID in Online Media
Back in the pioneering years of
writing for online help (and later
for the Internet), it was observed
that readers consume information
differently when reading online
content vs. reading printed documentation. There is less real estate (room)
on a screen to display information,
so we had to write more concisely,
learning to “layer” information.
For example, a high-level
procedure for running end-of-year
payroll reports could be:
1. Select one or more companies.
2. Select one or more employees.
3. Select the report(s) needed.
4. Run the reports.
To “layer” the information, you would
expand one of the steps:
1. Select one or more companies.
a. From the File menu, select
Company. A list of companies
will appear.
b. Click on a company, or hold
down the <Control> key and
click on multiple companies.
c. Click OK.
2. Select the employees.
3. Select the report(s) needed.
4. Run the reports.
Technically, we first accomplished
this with secondary windows and
later (with the advent of dynamic
HTML) by expanding the steps using
drop-down icons.
This is progressive information
disclosure: giving consumers the exact
level and amount of information they
want, when and where they want it.
One could apply this concept
further by providing a link to even
more information (on the Internet, in
a local PDF document, etc.).
1. Select one or more companies.
a. From the File menu, select
Company. A list of companies
will appear.
b. Click on a company, or hold
down the <Control> key and
clicking on multiple companies.
c. Click OK.
For more information about
running reports for multiple
companies, read Running
quarterly payroll reports.
www.stc.org
Content consumers today are used
to seeing “for more information” links
on Facebook, in blog posts, etc. In
fact, I’d say those of us who regularly
consume online content expect to see
them and even get annoyed when we
don’t. We like progressive information
disclosure—it enables us to receive
just the right amount of information
we want on any given topic.
This is especially true for people
who (by choice or necessity) have to
review large quantities of information
in one sitting.
Also consider how many channels
of information one might have to
monitor. Personally, I sometimes
feel overwhelmed keeping up with
people I follow on Twitter, friends on
Facebook, daily news, trade magazines
(such as Intercom), etc.
I have to be able to scan and quickly
identify which topics I can live with
just knowing that they happened (a
headline), which topics I want to read a
little more about (an interesting event),
and which topics I really want to dig into
(such as new development in my field).
Which brings me to my careerchanging realization.
TMI!
While driving to work listening to NPR
News, they played a segment about
Nelson Mandela that was interesting
… for the first minute or so. But then
they kept providing more and more
information (much of it repetitive).
Finally, I thought to myself, “TMI!”
(“too much information!”), and I
turned off the radio.
I’m so used to progressive
information disclosure online that I
got frustrated not having control over
how much information was coming
at me (well, more control than just
turning off the radio).
Consider that the next generation
of content consumers are used to
communicating by text message,
playing fast-paced video games, and
watching fast-edited movies and music
videos. Like me, they just don’t have
the patience to read long, boring
reams of Too Much Information.
In the silence that ensued after I
turned off the radio, I realized I’ve
had that “TMI!” reaction before. In
fact, it happens often.
For example, I asked a simple
question recently while interviewing a
job candidate by phone that required
a yes/no answer—“Do you have
experience creating printed and online
help from a single source in Flare?”
The candidate, in turn, started
talking about how long he’s used Flare,
why single sourcing is a good idea, the
projects he’s done, etc. Finally, I had to
interrupt him (TMI!) and say, “Thanks,
but just answer the question, please.”
If his answer was “No,” I could
have gone on to the next question. If
it was “Yes,” I could have said, “OK,
tell me about it,” or, “Great, here’s the
next question.” But he didn’t give me
that option—he just kept giving me
information, information, information.
I suppose I could have waited for
him to get to the point, but I didn’t
have time.
People are constantly asked to do
more with less, and managers these
days have more direct reports than ever
before, so time management is critical.
I know I’m not the only person
to have such a reaction to too much
information. A client of mine has
a great response when one of her
employees gives her TMI:
“Good usability includes ideas like progressive
disclosure where you show a small number of features
to the less experienced user to lower the hurdle
of getting started and yet have a larger number of
features available for the expert to call up.”
—Jakob Nielsen, author of Prioritizing Web Usability
29
Advancing Your Career
Manager: “Is the project done?”
Employee: “Well, I first I had to do
this, then I had to do that.…”
Manager (interrupting): “Don’t
tell me about the labor pains. Just
show me the baby.”
PID and Career Advancement
So how can you apply this idea about not
providing TMI to further your career?
44Actually listen to the questions you
are asked and answer accordingly.
This applies in a job interview, in a
meeting with your boss, etc.
44Look for visual clues and feedback
as to how much information each
person wants. Start with just a
sentence or two and pause. If the
person wants more information,
they’ll tell you.
44Pay attention to the types of
information particular people
want more or less of. For example,
your boss might consistently want
more information about project
status and less information about,
say, problems with co-workers.
The saying “know thy audience”
absolutely applies to progressive
information disclosure.
44Be aware that the higher a person
is on the organizational chart,
the less time he/she has to spend
with individuals. You might
get a whole hour to pitch your
proposal for buying a content
management system to your boss,
but five minutes to pitch that
same idea to your company’s CFO.
By using progressive information
disclosure in both your printed
and verbal communication, you
can address the information
needs of multiple audiences.
44Finally, realize that how much
information is “too much
information” varies from person
to person, and even day to day (or
hour to hour) for any single person.
Your spouse might ask you daily,
“How was your day?” and normally
be interested in an hour-long
discussion. But if (s)he’s tired or
hungry, you might cross the TMI
threshold in 30 seconds. Part of
communicating is observing the
reaction of the others involved and
adjusting accordingly.
Monitoring and adjusting the
amount of information you provide
others is a learned skill, one you may
need to practice. Chellie Campbell,
author of Zero to Zillionaire, says it
takes three weeks of daily practice
before an action becomes a habit.
Progressive information disclosure
is providing just the right amount of
information where, when, and how
the consumer wants it.
Sharpen your workplace PID skills
and see if you don’t start getting
more praise, better assignments, and
increase your standard of living. gi
i*KPJOFE45$BGUFS*UPPLBKPCTFWFSBMZFBSTBHP
BTBMPOFXSJUFS45$CFDBNFBOJODSFEJCMZ
WBMVBCMFSFTPVSDFGPSNF‰GPSFEVDBUJPOGPS
MFBSOJOHBCPVUUIFQSPGFTTJPOBOEKVTUGPS
NFFUJOHBOEDPOOFDUJOHXJUIPUIFSQFPQMFJOUIF
ëFME"T*IBWFCFDPNFNPSFBDUJWFJO45$*IBWF
HPUUFOFWFOHSFBUFSWBMVFGSPNNZNFNCFSTIJQ
ɥFMFBEFSTIJQFYQFSJFODFIBTCFFOJOWBMVBCMF
BOE*IBWFGPSHFEGSJFOETIJQTXJUITPNF
BNB[JOHMZUBMFOUFEQFPQMFw
.org/renew
30
September 2013
FYI
Mark Your Calendar
Organization events across the globe
2
1
7
5
3
64
F.Y.I. lists information about nonprofit
ventures only. Please send information
to intercom@stc.org.
310–12 Oct
The Council for Programs
in Technical and Scientific
Communication (CPTSC) is
holding its annual meeting
in Cincinnati, OH, at the
University of Cincinnati. For
more information:
CPTSC
www.cptsc.org
1
30 Sept–4 Oct
The Human Factors and
Ergonomics Society
(HFES) will hold its 57th
annual meeting at the
Hilton San Diego Bayfront
in San Diego, CA. For more
information, contact:
HFES
+1 (310) 394-1811
info@hfes.org
www.hfes.org//Web/
HFESMeetings/2013​
annualmeeting.html
www.stc.org
4
26–29 Oct
210–12 Oct
The Rocky Mountain
Modern Language
Association (RMMLA)
is holding its annual
conference in Vancouver,
WA, at the Hilton Vancouver
Washington from 10–12
October. For more
information, contact:
RMMLA
www.rmmla.org
The Public Relations
Society of America (PRSA)
hosts their international
conference, “One World:
Connection. Community.
Collaboration” at the Philadelphia Marriott Downtown
in Philadelphia, PA. For
more information, contact:
PRSA
+1 (800) 350-0111
www.prsa.org/Conferences/
InternationalConference/
66–9 Nov
51–6 Nov
The American Society for
Information Science and
Technology (ASIS&T) will
hold its Annual Meeting,
with a theme of “Beyond
the Cloud: Rethinking
Information Boundaries,”
at the Centre Sheraton in
Montreal, QC, Canada. For
more information, contact:
ASIS&T
asis@asis.org
www.asis.org/asist2013/
am13cfp.html
The American Medical
Writers Association
(AMWA) will hold its 73rd
annual conference in
Columbus, OH. For more
information, contact:
AMWA
+1 (301) 294-5303
amwa@amwa.org
www.amwa.org/
events_annual_conference
76–9 Nov
The American Translators
Association (ATA) will hold
its 54th annual conference
at the Marriott Rivercenter
in San Antonio, TX. For
more information, contact:
ATA
+1 (703) 683-6100
ata@atanet.org
www.atanet.org/conf/2013
31
My Job
Dear Technical Writing:
A Love Story
Dear Technical Writing,
I know I said I wouldn’t contact you again, that it’d be a
clean break, but it’s not. Not at all. I guess I was kidding
myself, so I’m going to lay it all on the line. I’m definitely
not that girl in the rom-com movies who rassles up her
self-esteem and gets her groove back. Because truthfully,
you are my groove. And I do want you back.
I know I left you. I’m going to shoulder all the blame
here. How could I have ever known? The grass isn’t greener
on the other side. It’s just . . . dead grass. That’s sort of how
I’ve been feeling without you. Won’t you come along and
mow, reseed, resod, and grow me again?
It was so great while it lasted, wasn’t it? Heck, it was great
from the start. I’m not afraid to admit we met through the
classifieds. I’d proudly tell anyone I found you in the paper.
I don’t know how you felt about me, but it was love at first
sight. I just knew. Yeah, it’s a classic movie cliché. But when
you know, you know. I took for granted my first job with
you, writing .NET software guides, but I didn’t know any
better. But I learned. I actually really did learn. Remember?
I went to counseling for it even. And when I graduated from
that counseling with a master’s degree in technical communication, you were right there by my side.
There were always the haters. People who just didn’t
understand us. Those who didn’t know or get it. Those
who think the words “nerd” and “geek” and “smart” are
insults. They said, don’t you want someone more creative?
They said, how can you stand to do that day in and day out?
Don’t you feel constrained? Oh, lordy, no. I’ve never felt
more satisfaction than sitting down and working through
things with you. Because you understand. You get the thrill,
the romance of documenting it all. Every punctuation mark
in its place. Every sentence needed, justified, checked. We
made sense together, in all senses of the word.
For a while, after I left a bad job and began freelancing
full time for myself, it was just you and me, babe, against
the world. We were killing it. It was so good. And then,
like an idiot, I left you. In all fairness, I tried to take you
with me. But in packing up a house and a cat and moving
entirely across the country, I lost you. I didn’t mean to, I
thought you were coming with me. Yet when I arrived and I
unpacked every single box, I couldn’t find you. As much as I
32
scraped, checked under rocks, pounded the pavement, and
called out your name, you were gone in the wind.
But I wasn’t about to just let you go. Wherever you were,
I would find you. The problem is, I haven’t yet. It’s not that
I haven’t been looking. When I settled into my place on
the West Coast, I rushed out to where I thought you were
waiting. It felt like our first date all over again. But you
weren’t there. I feel like my ties to you are being shredded.
Where are you, my love?
www.shutterstock.com /ra2studio
By Anonymous
I’ve tried to find you so many ways. And then—I’m
too upset to admit it, but I have to be honest—I settled.
There’s someone else. His name is Marketing and, well, I
guess we’re “together” now. He’s not you. He’ll never be
you. He doesn’t know about you, either. He doesn’t know
that while I seemingly enjoy our dates of blogs, PR, and
promotional offers, I’m thinking of you. Well, he may have
a clue. A couple weeks into our “relationship,” I got into
such a knock-down, drag-out fight about punctuation with
a coworker that it may have been a little obvious. You would
never doubt me on an Oxford comma. You would never
allow printed material to go out with typos. It’s you, it’s
always been you, and it will always be you.
I know you’re out there. I miss you so, so much. I’ve
never given up trying to find you. I know I have “him,” but
I will remain looking for you until I find you. You have my
word and all of my love, and as you know, it’s punctuated
correctly. gi
September 2013
Author XML/DITA content faster and smarter
Upgrade to Adobe® FrameMaker® 11
Scan to read what industry experts have to say about Adobe FrameMaker 11.
Adobe, the Adobe logo, and FrameMaker are either registered trademarks or trademarks of Adobe Systems Incorporated in
the United States and/or other countries. All other trademarks are the property of their respective owners.
© 2013 Adobe Systems Incorporated. All rights reserved.