RE: Tech Writing Question

["Kane, Beth" <Beth -dot- Kane -at- ncslearn -dot- com>]

Hi Richard-san,

Coming out of lurk mode for this...I've been a tech writer for 11 years, and
I've never seen a spec (functional specifications). However, I hear that is
the way it is _supposed_ to work. I've just worked for loosely-structured
engineering departments. Ask your developers if they have any specs, and you
might find them helpful. BUT I've done just fine by using/testing the
application to be documented myself, plus interviewing the engineers about
any questions I have about the app. You have to do that anyway -- the specs
won't be enough. You have to put yourself in the users' place. You can also
get help/explanations from the QA test dept., if the engineers are too busy.

You'll find with your fresh pair of eyes, you will find bugs or bad things
in the UI (things that make it not intuitive, for lack of a better term)
that you can point out to them, and then they will improve it (I hope)
before it's released. 

Users are task-oriented thinkers. All they want to know is: What do I have
to do to get the job done (the job being whatever it is your app helps them
do). They just want to know HOW TO do it. Task-Oriented = How To. 

If developers start telling you that the users need to know the entire
theory behind the app, tell them that's secondary and can go into an
appendix IF there's time to get to that. Keep them on the how-to track in
your interviews, at least until that part of it is finished. Your users will
be much happier if you simply walk them through the interface to get the
tasks done. Leave all the background info for the appendix(es). It's nice,
but secondary.

KEEP IT SIMPLE and the users will love you for it! And format with plenty of
white space on the left side of each page. It's easier to read instructions
in a narrower column. And make your headlines follow an obvious hierarchy:
header 1 bigger than header 2, header 2 bigger than header 3, etc. 

Include screen captures so they know they're in the right place. Plus, you
can use call-outs (pointers to parts of the window that you captured) that
explain stuff about it. As it gets closer to release time, you might have to
recapture windows that have changed. 

Don't forget to keep yourself in the new users' shoes -- YOU are the User
Advocate. Remember every crummy manual you have read that made you hate
manuals, and try hard to write more concisely and clearly than everyone
else. Even I hate to read manuals; experience has shown me the vast majority
of them suck. 

Beth Kane 
Sr. Technical Writer
Instructional Services Support
NCS Learn, an NCS Pearson business
5451 E. Williams Blvd., #151
Tucson, Arizona 85711
Phone: 520.784.7048 or 
1.800.242.7117, x7048 
beth -dot- kane -at- ncslearn -dot- com
www.ncslearn.com


-----Original Message-----
Is there often a step where the tech writer has access
to some type of spec type documentation or writers
just start from scratch?


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

---
You are currently subscribed to techwr-l as: archive -at- raycomm -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.