Re: 'Old fashioned' Tech Writers

Subject: Re: 'Old fashioned' Tech Writers
From: John Posada <jposada01 -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sun, 11 Jul 2004 06:29:11 -0700 (PDT)

The mantra we hear over an over again in tech writing is "Write for
your audience. Write for your audience." Yet, as soon as an effort is
made to exclude a category of user because they "might" be an
audience even though they haven't been identified, or refuse to write
about a feature with which only 1 out of 100 users "might" do
something some way, then we scream bloody murder.

What do you think "write for your audience" means? To me, it means.
don't write for someone who ISN'T your audience.

How do we do that. Maybe you need to study the target marketplace and
figure out who that user is? I can't speak for all companies, but we
spent MORE than a full year interviewing and observing a substantial
number of potential users to identify who that user is before writing
one line of code. don't do this by seeing how they use your existing software
and modify it for the user...I saying you do this from the ground up.
How do they do their job, then you design the application to help
them do it.

--- TechComm Dood <techcommdood -at- gmail -dot- com> wrote:
> > 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


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

You don't writer the manual for the "first-time-user" You write a
separate manual to train the first-time user to bring them up to the
level where they can use your application, at which point, they are
now your targeted audience.

Example. We identified three personas; user, system administrator,
and network/database manager. I didn't write a manual for all three.
I wrote three completely different manuals and three different
training tracks.

> 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"?)

It is still mice.

> > I had to put in an annex that explains, in excruciating 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.

Are you assuming this or are do you know this through observation?

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

Correct...the point of UI is not to condense the manual into so much
garbage on the screen. The point is that you design the application
so the user doesn't have to learn anything new. You use their
language. You use their workflow. You use their thought process. The
user KNOWS what to do next to do their job. Your job is to design the
interface so what the user who already knows to do next sees in the
application how to do it and that the application doesn't get in the
way of them doing it.

John Posada
Senior Technical Writer

Do you Yahoo!?
Yahoo! Mail - 50x more storage than other providers!


ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!

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!

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 for more resources and info.


Re: 'Old fashioned' Tech Writers: From: TechComm Dood

Previous by Author: Re: Outline dilemma
Next by Author: Re: STC Transformation -- info
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