Other kinds of technical writing

[Ben Kovitz <apteryx -at- CHISP -dot- NET>]

Tim Altom mentioned this when replying to my suggestion of
replacing metatext with introductory content:

> >Introductory content:
> >
> >    2.1 The Job View Window
> >
> >    The Job View window displays and lets you edit all information
> >    pertaining to a job.
>
> We'd argue, though, that it's best to just shift to a task
> paradigm, rather than mingling it with a system orientation of
> "this window, that window...".  Users are task-performing
> creatures, not system appendages.  They use window names only as
> occasional roadside markers, not as central characters in the
> drama they play out every day.

I'm totally with you, of course.  Most user's manuals should mainly
explain how to perform tasks, not describe system capabilities on
the expectation that users will creatively combine those
capabilities to get something useful done.

However, changing the topic, there are a lot of other forms of
technical writing than writing user's manuals.  For example, a
user-interface design document, meant to be read by programmers
and testers, would probably need a section about the Job View
window.  It's especially in internal documentation that I've seen
metatext almost completely supplant normal text.  I once saw a
20-page UI design document that had only two pages that described
specifics of the UI (and left out most of what needed to be
said).

(In a UI design doc, btw, I wouldn't say "you" in the above
sentence.  It would probably go, "In the Job View window, a user
can display and edit all the information pertaining to a job."
Btw, "changing the topic" in the previous paragraph was
metatext that I just couldn't bear to chop.)

So here's the question on my mind.  Who should write these other
kinds of technical documents?

More to the point, should system analysts and engineers and
programmers and UI designers acquire the kind of skill at
technical writing that we have?  Or is it a better division of
labor to have a technical writer write their design documents for
them, treating them as SMEs just the same as when writing user's
manuals?  Or is the best mix something in between?  Is there a
lot of technical-writing know-how that is specific to these other
kinds of documents, such that someone skilled at writing user's
manuals wouldn't necessarily be much help in writing design
documents?  Or does most technical-writing know-how carry across
most forms of technical writing?

By the way, that 20-page UI design document of nothing was
written by someone with about a decade of experience as a
technical writer, mainly writing user's manuals at a major
telephone company.  In fact, he was considered *one of the best*.
Worst of all, he was.

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Boulder, Colorado


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