Re: Writing Technical documentation

Subject: Re: Writing Technical documentation
From: "Lindsay Burrell" <lburrell -at- telus -dot- net>
To: "TECHWR-L" <TECHWR-L -at- LISTS -dot- RAYCOMM -dot- COM>
Date: Fri, 26 May 2000 22:28:40 -0700

Jill Kenny wrote:

> I'm being asked to write and assist in writing highly technical documents
> for our software development center. These documents include technical
> design docs, architectural overviews, application roadmaps, and
> methodology descriptions. Do these types of documents fall under the
> category of technical writing? And if not, any suggestions on how to
> gracefully bow out of these tasks.

We write anything we can, for anyone who will have us.

We take it that we have a unique and valuable skill set in the company, and
have the capability to add value in writing tasks company-wide. So we
welcome (invite, even) tasks from Human Resources (Policy and Procedures),
programmers (writing up their programming language specifications, object
descriptions and APIs), sales engineers (installation procedures), GUI
designers (writing work flows; we have usability expertise different from
theirs, and it helps us write the end-user docs), GUI implementers (we copy
edit their screens) and Marketing (we provide copyediting and substantive
editing for their datasheets, technical articles posters and White Papers.)
On principle, we write everything they will let us get our hands on, from
the sublime to the highly technical, to the rediculous. The invitation is

In return, I think we have greatly reduced, perhaps eliminated, one of the
chief beefs I hear from tech writers: "My company does not see how tech
writers add value." Our goal is that every individual in the company is
perfectly clear on how tech writers add value.

It also fosters cooperation from other departments when we need a favour, or
other help of some kind. And of course, it adds to the overall quality of
our product and our corporate image by helping ensure we adhere to corporate
style and usage standards--and the marketing material goes out without typos
and spelling errors (and hyphens where their em-dashes should be). From an
individual standpoint, the more kinds of documents I know how to write, the
more marketable and valuable I'll be. Everyone wins.

The caveat is that you retain enough of your schedule to write your prime
deliverables, usually end-user docs. This is just a matter of sheduling
other departments in, in the same way you would schedule anything else. It
is really nothing more than being able to set reasonable limits, which one
must do in other ways in any case.

Our manager has handled it by saying we may use up to X % of our time
providing tech writing services to other departments. In addition, around
product release time, we are as busy as you-know-what, and we are

But after all, not everyone wants to make a career out of knowing when you
want to use a hyphen and when you want an em-dash. Still, those who do have
a lot to offer, and a lot to gain, by sharing their expertise around the

Em-Dashes Where Her Brains Should Be,

Previous by Author: Re: initiating successful technical communications
Next by Author: Attaching Templates to Word Documents
Previous by Thread: Re: Writing Technical Documentation
Next by Thread: RE: FullShot w/ Win2K

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

Sponsored Ads