Re: Value of technical writers - Sort Of.

[Tom <eagles -at- CONNECTION -dot- COM>]

> -----Original Message-----
> From: Bernie McCann

> One has to assume from this statement

<which I snipped, because this thread is getting
l-o-n-g and I would have had to include my
comments and the comments I was commenting on to
put it in perspective. Instead, let me
summarize. -ed>

> that Tom believes that it is not the
> fault of Technical Writers, but fails
> to place any blame... <snip>
> If the Technical Writer is a qualified
> professional, then, it would be her
> fault because she should know better,
> but if she is unqualified to know this,
> then, we should blame the person who
> hired her to carry out the task.

The above comments are in regard to whether docs
can be done properly if you're not SME in the
subject, or at least well on your way to being
one. If one is truly a tech writer then one will
know if they are getting in over their head and
need additional training before tackling a job.
Some companies have reluctant SMEs who will
stonewall tech writers. I worked for a risk
management software company (their software sells
for between $500,000 and $1,000,000 per license).
The math involved in the formulas and in the
understanding of the internal workings of the
THEORY behind the software is mind-boggling. I, of
course, did NOT go back to school to learn the
math. Forget that. I relied upon SMEs. First of
all, I relied on marketing people to give me an
idea of what kind of users would be using this
software (they weren't much more adept at math
than I, as it turns out, so users' grasp of math
wasn't an issue). Then I asked the programmers to
explain the functioning of the software. Finally,
after a first draft, I had the marketing guy test
the software using my instructions. Finally, I
tested the software using my instructions. I had
chapters on 'Getting Started', a brief tutorial,
trouble shooting, mathematical theory and
comparatives. I also had excellent SMEs. Mission
accomplished. Ninety per cent of the people
working for this company (150 people) have PhDs in
math. Needless to say, I don't. But I checked and
double-checked my work to be sure it served the
user.

Granted, not everyone works for companies where
cooperation is available from SMEs. In those
instances you do your best and admit when you're
in over your head <"I'm not getting the
cooperation I need to write the damn thing!">

> Yes, Tom, if it requires becoming an
> engineer, or a taking six-year course, so
> be it, but in most cases this will be
> unnecessary.

Most? I'd say that in instances where you need to
go back to school, you are either not getting the
cooperation from the SMEs or you are inexperienced
at putting together a manual. Distilling things
down to a simple understanding SHOULD get you
started. After that, you rely even more on SMEs to
make sure the complexities are properly
explained/defined. That should work. Anything too
complex for a tech writer to write a manual for
probably doesn't belong in the public domain. <g>

> On the other hand, simply
> adopting the journalistic philosophy,
> i.e., It'll be OK as long as I know what
> questions to ask, will, undoubtedly,
> create a poor quality publication.

Undoubtedly. If you are satisfied with whatever
answer you get and don't test the answer by
explaining back to the SME what he/she just told
you. If you get it, so will the user, in most
cases. For those cases where that's not true, you
test it on other guinea pigs before going to final
draft.

> We should be known as, either;
> engineering, scientific, software, hardware or
> marketing, etc., writers, and be very
> cautious about straying into 'terra
> incognita'.

That certainly makes it easy. Stay with what you
know. Can't go wrong if you do that. Can't grow,
either. And can't know if you have the wherewithal
to make it elsewhere, either. In very rare
instances, there might be jobs where it's best not
to

Bernie quoted from Eric:
> It's in having a sufficiently
> developed BS detector to tell
> what's likely to be
> legitimate and what's not.

Interesting. I thought that I said the same thing.
<g> Eric and I (in this instance, at least) think
alike.

And also quoted from Eric:
> I don't need to know if the
> info I get from a developer is
> completely accurate or
> not, at least not on the first pass. I
> need to be able
> to assess how credible the information
> is and if it
> meets the WIML test.

Exactly. And if the information is beyond your
understanding, and there is no time to have it
properly explained (so that YOU can properly
explain it in turn), then let those who hired you
know that they hired the wrong guy. It'll mean
that you maintain your integrity and bridges
aren't burned. If it was a job placement by an
agency, then shame on them for not properly
assessing your suitability for the company. And
shame on the company if their hiring expectations
are unrealistic, and don't allow for ramp up time
if their product is obscure or particularly
complex. Not too many PhDs in math, for instance,
are also good technical communicators.
Alternatively, if they do offer you the time and
resources, seek more help. But, getting a PhD in
math to write a manual is absurd, perhaps even
neurotic.

> Until we come to terms, ourselves, with
> these definitions, how on earth can we
> expect the world of the head hunters to
> play a useful role in our profession
> and, perhaps, teachers to teach
> (Although I do not consider the latter as a
> great problem, currently).

I expect them to know that some tech writers have
certain areas where they'll need very little ramp
up time, and to know their clients' needs well
enough to know what sort of individual best suits
them, and what skills the tech writer will need -
if any beyond writing skills, interviewing skills,
and DTP skills. As for teachers, they should have
to be tech writers first - and then they'll know
what skills we need.

On a final note, I'll add that (clearly) most
people will be more efficient if writing about
something they know (software, contract proposals,
chemical engineering - whatever the case may be)
rather than something they need to learn from
scratch.

Tom Eagles
Technical Communicator
eagles -at- connection -dot- com


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=