What I want to say....

Subject: What I want to say....
From: "Chuck Martin" <cm -at- writeforyou -dot- com>
To: techwr-l
Date: Tue, 20 Jan 2004 12:15:32 -0800

A recent job post, which I may or may not apply for:

"This contract Senior Technical Writer position must work independently
under minimal supervision and direction provided by the CEO. [Company] is
releasing a new version of its web application. This application has a large
number of complex statistical algorithms which need to be documented in a
user friendly manner. So a demonstrated ability to clearly communicate
difficult algorithms is a plus. In addition, we're updating the web
interface for the product. This project entails writing two documents that
describe the application, a sysadmin manual and a users manual, as well as
updating the on-line help. There are no other technical writers/editors on
staff, so you will have responsibility to deliver customer-ready
deliverables. It is expected that this job will take 3 months.

Job responsibilities include:

- Write installation and maintenance guides for system administrators.
- Write user manual for users of the web site.
- Prepare on-line help documentation targeted at end-users, who are
generally transportation professionals.
- Develop coursework and curriculum for installation, operation and
maintenance training programs.
- Work with development team and product marketing to review, edit, and
generate final copy of the documentation.
- Work with development team to obtain product information.
- Quickly attain subject-matter expertise in all areas of project.

Job requirements include:

- Demonstrates a high level of technical writing ability including clear,
concise, well-structured writing and an ability to adhere faithfully to a
style guide; accuracy and consistency; avoids the use of jargon.
- Fluency with: LaTeX, Adobe FrameMaker, HTML generation, drawing programs.
- Understanding of UNIX operating systems.
- Experience authoring web-based help and hard copy manuals.
- Exceptional english communication skills.
- Ability to quickly grasp and communicate technical concepts.
- Coordinates and completes projects with minimal supervision; is proactive,
flexible in contingency planning, and skilled at prioritizing.
- Has a bachelor's degree, preferably in English, Journalism, or Computer
Science (or has equivalent professional and/or academic training).
- Has related subject-matter expertise (for example, web-based applications
software and relational databases).
- Work must be performed at [Company] facilities in [Location]. "

I'm reacting at a bit of a visceral level at this, so please forgive me if I
sound harsh. I think I'm reasonably well qualified for this--especially as
I've spend most of the last few years documenting web applications, yet the
past year and a half has shown me that even being a near-perfect match
rarely even gets me a phone interview, never mind the job. So I thought I'd
vent a bit here, then decide whether to try an apply to this one.

What I *want* to write instead of an application letter:

This is in response to you recent post for a Sr. Technical Writer. Unless
your web application is fairly small and simple (and from you web site it
doesn't appear to be), you may be setting yourself up for failure. Here's

First, you're asking for a "high level of technical writing ability," yet
you want someone with a degree in a discipline other than Technical
Communication. Does this make sense to you? Do you look for web programmers
with an MBA? A CFO with a degree in Political Science?

I just finished a contract where I almost completely redesigned and rewrote
the User Guide for a web application, comprising several hundred pages of a
web-based help system (including reorganizing the contents and adding a
complete new set of index keywords) plus a 200+ page printed manual, added
content for new functionality and updated terminology throughout in a 200+
page Administrator Guide, created a 2=page Quick Start Guide, and updated
two training guides. This took about 5 months. I'm wondering: if you have no
one as a part of your team experienced in the discipline of Technical
Communication, where did you get a 3-month estimate for the work you need

Learning about a product is not done in a vacuum. While I (and many other
technical waters) are quite technically competent, are programmers and other
members of your team going to be available to transfer product information,
or will they be "too busy" to work with me?

From what I can see on your web site, your product is aimed at a specific
industry. "Avoiding the use of jargon" should *not* be one of you goals.
Rather, the jargon that your product's users understand to do their jobs
should be an integral part of the documentation because if you try to avoid
the terminology that is a part of their life, you will make them work harder
to understand what you're trying to say. (It probably would also take more
valuable space to say it.) Avoiding jargon doesn't necessarily equal "user
friendly" because industry-specific jargon might be most beneficial to

To me, a technical writer who has plenty of experience writing both for a
varied (and sometimes technical) audience and for web applications, these
things are obvious. I am sure you will get many applications telling you
what you want to hear, and it is entirely possible that "someone* can get
done in 3 months. More than likely, someone is going to put in some very
long hours (not that there is anything wrong with that) and take shortcuts
that you'll both be unaware of and not understand to meet that 3-month

As a matter of fact, if you truly want to release in April (if this is for
the product on your web site touted for an April release), then the task
actually isn't writing in 3 months, but in 2. The rest is needed for
reviewing, editing, and debugging, and the reviewing part takes the time of
other members of your team. Is that in your schedule?

Why working under the CEO and not the product manager? Does the CEO have
experience working with technical writers? Does the CEO understand the
basics of planning, designing, and producing technical documentation, the
tools needed to do the work, and the information needs from other members of
the development team?

Of course, such things wouldn't result in an interview even in the market we
had 5 years ago. I know that no one likes to be told that they are
wrong--least of all a CEO--and that's just what this does. It's certainly
not the way to win the job opening, even if I did want it, which I'm not
sure I would. I just have to wonder about what the working conditions in
such an environment where it appears that there is an undercurrent of
unrealistic expectation fueled by an ignorance of what the job probably

And I could be wrong about how much work is required. It's happened once or
twice before. :)

But as I mull over whether to apply for this one (is the stress this might
induce worth it, but then, it's not like jobs are coming out of the
woodwork, I need to pay the rent, and I've had only one in-person and one
phone interview since the start of the year), there are probably dozens or
hundreds of others filling up the recipient's mailbox. My experience tells
me this one's a fool's errand, while my hungry stomach says to go for it,
that something good could happen. Which gut do I listen to?

Chuck Martin
User Assistance & Experience Engineer
twriter "at" sonic "dot" net www.writeforyou.com

"I see in your eyes the same fear that would take the heart of me. The day
may come when the courage of Men fail, when we forsake our friends and
break all bonds of fellowship. But it is not this day! This day, we fight!"
- Aragorn

"All you have to decide is what to do with the time that is given you."
- Gandalf

Previous by Author: Re: It shouldn't be that hard to write good doc, should it?
Next by Author: Re: What I want to say....
Previous by Thread: Access and html templates
Next by Thread: RE: What I want to say....

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

Sponsored Ads