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.
Gene Kim-Eng [mailto:techwr -at- genek -dot- com] sez:
> I don't see how this would be any different from writing any
> other document. Or should we segue into a discussion about
> how many technical writers are working on documents that
> are potential liability timebombs for their companies/clients
> because they never get vetted by marketing, customer service,
> safety or legal reviewers?
I'm swinging in both directions on this one.
On the one hand, virtually any document is a potential timebomb in that
respect. There's a reason that marketing blurbs and "collateral"
materials are a different skill than tech writing. It might be two hats
on the same person, but keep 'em straight.
As a techwriter, I can protect myself by documenting what the product
_does_, and limiting my suggestions or speculations about what it
_could_ do to stuff that we know our customers (or competitors'
customers?) are already doing, or are actively investigating in concert
with our own engineers. Or by using defensibly vague language. If you
include "possible uses", that's about the only place in a technical doc
that vague language might be permissible.
I'm thinking that some kind of fitness-for-use disclaimer might not be a
bad idea. [Note to self: add one.]
At more mature companies, the procedure and documentation trail that
goes along with the product-dev-and-release process can help you to
avoid gaffes (been there...) like writing to the spec and not being
aware that this or that feature or command or module was left out of the
released version due to lack of time or resources in dev or testing. Or,
like missing that they split this one command into three at the last
moment. That is, at the fast-and-loose younger companies, if there are
specs documents more formal than a scribbled napkin or matchbook, you
often get requirements docs and response-from-engineering docs created,
but they don't get updated as "life happens" during actual development.
The more mature company has those (and many other) docs _and_ they have
milestones at which those documents are checked and updated, so they
_do_ catch the changes inflicted by "life happening". Rev A of the
"Statement of Work" is a pretty good answer to Rev A of the "Marketing
Requirements Document", but Rev E of the SoW is not only different from
Rev A, it's now a pretty good answer to Rev D of the MRD _and_ a pretty
good depiction of "what we actually did and are actually releasing".
So, when the company is tiny, and you are the only writer, and you live
in the same room with a handful of engineers or coders and _the_ tester,
you tend to pick up on all the little changes, additions, retractions
that happen, because it's all part of the conversation going on around
you.
When the company gets a bit bigger, you might still be the only writer,
but there are multiple groups of developers working on several projects
or variants, and you just can't be everywhere at once. Naturally, you
maintain good relations with everybody, and they try to keep you
up-to-date and they include you in the meetings and you get the minutes,
and so on... but they forget to tell you things. They don't remember to
add you to each and every e-mail thread as soon as the threads get
interesting. They use the same keywords and buzzwords over and over such
that anybody could get confused about which project just had
this-or-that feature dropped or pushed back.
Eventually, the company notices that it's not just the techwriter who
misses some boats, and they start building those mature processes... you
hope.
All you need are a few fiascos in manufacturing/fulfillment and they
forget that feature that you documented - and a customer tried to use -
that was deferred until a later release. :-)
Not saying that such a thing ever happened to me, personally... not
_saying_ precisely... but I do have this here T-shirt...
Kevin
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
