TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Thoughts on working WITH developers... From:"Eric J. Ray" <ejray -at- RAYCOMM -dot- COM> Date:Thu, 25 Mar 1999 11:38:56 -0700
I've been watching the messages go by about working
with developers and various ways of coercing/bribing/
blackmailing/manipulating information out of them...
I wonder, though, why it seems that so many people start
out with the us vs. them mentality in the first place.
Don't get me wrong--I've worked in places where developers
were hard to corner and harder to get information out of
(but problems there could easily be attributed to an
unspec-ed inaugural OO project and relative inexperience
on the part of the writers and developers alike),
but I think that approaching the common task of
getting information for your documentation products
with any kind of us vs. them attitude is probably a key
part of the problem.
Ben, Geoff, Michele, and some others made good points about getting
information, but I'd say that one of the best ways to
work successfully with developers is to work _with_ them.
That is, interact with them just as you'd interact with other
tech writers in your group or in other groups at your company.
* Ask good questions or ask dumb questions, but make a real
effort not to ask the same questions twice.
* Understand the technology well enough to be able to make
coherent comments and suggestions. That is, if the
interface is HTML-based, don't waste anyone's time
asking if it's technically possible to change the wording on the
pages--ask who does it, or when, or under what
circumstances, but don't ask if it's possible.
* Respect the developer's time enough to do your homework
first. If you don't know even where to start, ask the
developers where to go to come up to speed. E.g.,
"So, if the boss came through with the bucks for a
junior coder to work with you on this project to help
out, what reading material would you give her on her
first day. Second? Third?", then go and absorb it.
* Work _with_ developers. If you find something that you
think is a bug/problem/issue with the product, then
make sure you know the name and face of the person
responsible for it, and ask the next time you run into
them in the halls. If you're sure you've found a serious
bug, gently ping them and ask if there are workarounds
that you should follow, or if you should file a bug report,
or if it's already being taken care of.
(This offers the same face and hassle savings that you'd
want if a developer finds an incoherent paragraph in your
latest draft...they could file a bug against the docs because
of your copy and paste slipup, or gently mention it to you...
In other words, be one of the team, and not just someone who
is always sucking information up and never contributing back.
If developers or QA are testing something and your particular
environment matches testing needs (or real world scenarios),
offer to help or let them "borrow" your machine. If you see
three paragraphs of incoherence in the opening screens of a
setup wizard that a developer did, rewrite the text and offer
it to the developer ...
Caveat...I'm working in a nearly ideal environment--I've got full access
to all of the same tools the developers use plus all of the tools
I need (and have great hardware etc. to run it all on),
I can (and am expected to) install the latest builds just as
the developers do, am expected to use the same tools
for code management and version control that the
developers use, and above all am working toward the same goal as
the developers are. That is, getting a good product out the
door on time and on budget. I'm in a group of tech writers,
but my boss and the developer's boss report to the same
person, so everything's tightly integrated. If my stuff doesn't
pass QA muster, the product doesn't ship--just like developer's
But, ideal environment aside, working _with_ developers
has ALWAYS been successful for me, and I've never had
to resort to coercion to get the information I needed.
Eric J. Ray RayComm, Inc. http://www.raycomm.com/ ejray -at- raycomm -dot- com
*Award-winning author of several popular computer books
*Syndicated columnist: Rays on Computing
*Technology Department Editor, _Technical Communication_