Re: 'Old fashioned' Tech Writers

Subject: Re: 'Old fashioned' Tech Writers
From: TechComm Dood <techcommdood -at- gmail -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 10 Jul 2004 10:09:14 -0400


> Ye gods, how I wish this statement were true. Unfortunately, it assumes a
> uniform level of familiarity with computers. You still have to match the
> granularity and the coverage to the anticipated skill level of the
> audience, and that is still a variable.

No, it's not a variable. The product you are documenting has a target
audience, and that target audience has a recommended skillset. You
write to that. You can't chase the lowest common denominator; if you
did you'd never reach the finish line (would be like following a sugar
ant).

> Technical writing is not always for a technical audience. What about a
> person who has just bought a computer for the first time? What about
> people who are trying to learn how to use something like Photoshop for the
> first time? There are some still out there, more than we'd like to think.

If that is your target then write for them. Otherwise you need to
write for your audience.

> I just finished doing a software user guide for a customer who is buying
> our product for use by employees who had never used personal computers
> before. Up until this very year they had done all their work on old
> green-screen dumb terminals. I had to design and write the manual on the
> assumptions that the users had never before worked on a system that
> included a mouse. (In computers, what the heck is the plural of "mouse"?)
> I had to put in an annex that explains, in excrutiating detail, how to use
> a mouse, what a pull-down menu is, how to scroll, etc. It is a real
> challenge to write a software user guide for people who may not know what
> the word "click" means.

I sympathize but I recommend you not document what isn't your product.
If the purchase of your product came with these new computers (that
is, you sold them the computers as well) then I can see an exception
to the rule, but ideally you should never document someone else's
technology in your product's documentation. It can potentially cause
more problems than it'd fix.

> I think companies will soon discover that the attempt to fuse the jobs of
> UI designer and tech writer can be pushed only so far. They both are still
> very different jobs, with very different requirements, and they are both
> full time jobs.

LOL, I'll bite, how so?

> The UI designer can put popup tips all over the interface
> to explain every feature on it; in most applications, that still does not
> tell the user *what to do next*.

I think you're missing the point of what a UI designer does.

> It does not give the user who needs
> information about a procedure a way to find procedural information.
> Creating help that addresses those types of concerns is still enough of a
> chore that you can't do that and design/write/debug the interface at the
> same time.

Well, I disagree. If the UI is properly designed, the task of the
technical writer for UI instruction becomes easier. Now, I wouldn't
say that the same UI designer should also be responsible for
documenting the API behind the UI or anything. But how is a UI
designer who also documents the UI any different than the programmer
who documents their code? [insert your joke here about programmers
writing documentation] We expect our programmers to document their
code - it's not "code complete" without it.

> I'm sure companies who want to cut their payrolls will try fusing the
> jobs. And eventually they will come full circle back to the discovery that
> created the position of techical writer in the first place - developers
> don't have the time to create products and document them both, even if
> they have the language skills.

I suggest not using a "all or nothing" perspective.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl

WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



Follow-Ups:

Previous by Author: Re: Longhorn - Tech writing changes
Next by Author: Re: What do you ask references?
Previous by Thread: RE: 'Old fashioned' Tech Writers
Next by Thread: Re: 'Old fashioned' Tech Writers


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


Sponsored Ads