Re: Writing Technical documentation

["Lindsay Burrell" <lburrell -at- telus -dot- net>]

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
development
> 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
out.

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
off-limits.

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
company.

Signed,
Em-Dashes Where Her Brains Should Be,
Lindsay