Re: "Design" was Re: Tech Writing a Growing Field?

Subject: Re: "Design" was Re: Tech Writing a Growing Field?
From: Ned Bedinger <doc -at- edwordsmith -dot- com>
To: Gene Kim-Eng <techwr -at- genek -dot- com>
Date: Sat, 07 Apr 2007 13:11:45 -0700

Opinion-wise, I agree with Harry that a strong development methodology
like the Capability Maturity Model (CMM) is a blessing for tech writing.
But perversely, software development organizations seem to be allergic
to any methodology that imposes documentation requirements on the
developers. They hiss and moan that it is a waste of time because it
doesn't fit the established way they work, etc.

The odd thing is that CMM is a framework, designed to be customizable
and modifiable so that it can fit any project in any programming
language. Still, I've seen the dev team break out in hives and gasp for
air at the very mention of working within a CMM-inspired methodology.
They're like wild horses at the round-up, yearning to be free.

I've been hired in the past to facilitate a dev team's transition to a
documentation-intensive methodology, and I've found that when management
makes it inevitable that development proceeds with a strong methodology,
I can smooth the transition by being versed in the documentation
requirements, and providing the developers with the templates and
outlines they need. I usually end up writing the dev docs anyway using
their notes and my SME interviews.

But woe to the tech writer who tries to drive such documentation
requirements without management direction. While I don't want to
stereotype developers, the ones I've worked with in software become bad
animals if they sense the slightest possibility that a tech writer ( as
opposed to their management) is requiring them to produce documentation.

I don't blame them, by the way. I think there's a valid cognitive issue
with shifting back and forth between code and English, and it is the
rare person who can do it and do it well. Programming is a style of
thinking that, for me at least, takes over the language center in my
brain, making English grammar seem like a horribly dull and arcane
requirement. Maybe people like me are wired differently--for instance,
when I learn a new langauge, it seems to push what I know about other
non-native languages out of my head. If I learn Portuguese, I can't
speak French anymore, the vocabulary and syntax become Portugee with a
French accent. But aanyway, for most developers I've worked with,
imposing a documentation requirement on them would be like asking a
plumber to fill out a bunch of forms detailing their design for plumbing
a house--they're thinking it is a bureaucratic-like waste of time, no
one will read it, anyone who needs to know can inspect the finished work
and will understand it without someone writing about it, ...

I think we'd have to start working with developers at a very early age
if we want to naturally slip into the kind of design role Chris B. was
talking about earlier in this thread. And as Harry implied, that design
role is essentially the role that a strong methodology plays. Tech
writers can have a good time working that way, but I grok Gene's
admonition about prefering employment . I'd have to say that the
opportunities to work in this design role are not the same as every tech
writing position, because many development teams just aren't ready,
willing, or able to invest more project time in becoming more mature in
the CMM sense. A tech writer who want to work that way in a group who
doesn't has to be very careful and willing to work with far less than
the optimal level of information.

There's a lotta love in this thread :-)

Ned Bedinger
doc -at- edwordsmith -dot- com

Gene Kim-Eng wrote:
> Well, I do to in an ideal work environment. However,
> my opinion on this takes a back seat to my desire to
> remain employed, at least until I can find another
> place that seems a bit closer to an ideal work
> environment to me.
> Gene Kim-Eng
> ----- Original Message -----
> From: <HBacheler -at- aol -dot- com>
>> I believe that all/most technical writers have the same viewpoint.

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.

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.


Re: "Design" was Re: Tech Writing a Growing Field?: From: HBacheler
Re: "Design" was Re: Tech Writing a Growing Field?: From: Gene Kim-Eng

Previous by Author: "Design" was Re: Tech Writing a Growing Field?
Next by Author: Re: "Design" was Re: Tech Writing a Growing Field?
Previous by Thread: Re: "Design" was Re: Tech Writing a Growing Field?
Next by Thread: Re: "Design" was Re: Tech Writing a Growing Field?

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

Sponsored Ads