Spec / product / interview?

Subject: Spec / product / interview?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 13 Nov 2001 14:16:21 -0500

Jane Carnall wonders: <<I've noticed that often technical writing job
adverts (or the job specs, or sometimes the interviewers) ask that the
technical writer should be able to provide a user guide with the product and
the spec (or sometimes just with the spec).>>

Which leads me to repeat Sue Gallagher's quotable line that as technical
writers: we're actually science fiction writers because we too write about
things that we _expect_ to happen. A really good functional spec lets you do
enough research to ask the developers intelligent questions, but rarely
provides enough information to fully document the product. I suppose that
with a frozen, clear interface and a detailed spec, we might actually be
able to meet this goal, but since neither is usually available, it's not
generally possible to do a good job this way. Like many other techwhirlers,
I've written documentation for a product that I've never actually seen, and
the docs worked about as well as you'd expect: good enough to be useful, but
not good enough to be something I'm proud of writing.

<<So: how to get managerial support for something that they think you don't
or shouldn't need?>>

If you've got a good enough relationship with your own manager or the
development manager that you can actually talk to them, it's easy enough to
do. Obtain a copy of the functional spec and find an area where it doesn't
even remotely match the product, then demonstrate this to the manager: "See?
It says that there are only two input fields, and both are integer values,
yet the software has three fields and each is alphanumeric: is the software
out of date, or the spec, and how am I supposed to know without asking the
developer? Also, nowhere does the spec describe any limits on the input for
these fields. How am I supposed to guess what the limits are? Do I have to
try every possible keyboard combination until I magically discover the ones
that don't work? Wouldn't it be easier if I just asked the programmer?" You
can make your case easily enough in this manner.

When in doubt, bypass the managers and establish good working relationships
directly with the developers. So long as you don't annoy them or take up
huge amounts of their time, most programmers are quite willing to provide
the answers you need. That's doubly true if you don't visit them solely to
suck dry their brains and if you come prepared, having done some research
and having developed intelligent, pointed questions; if they're friends or
at least happy to be working with you as a person, they're far more likely
to cooperate. And with rare exceptions, few managers will actually stalk you
and, when they catch you talking to a programmer, forbid you from ever
seeing that person again at lunch, in the halls, while waiting for the bus,
etc. If they do, maybe it's time to look for a saner job.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Law."

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



Previous by Author: PDF dilemmas?
Next by Author: Question: Federal Law for Private Information on the web?
Previous by Thread: RE: Reference guide
Next by Thread: RE: spec / product / interview?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads