Re: 10 Things All Technical Writers Should Do

Subject: Re: 10 Things All Technical Writers Should Do
From: Lee Hunter <lee -dot- hunter -at- hum -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 12 Nov 2004 10:07:16 -0500


Quoting David Castro <thejavaguy -at- gmail -dot- com>:

Who was quoting Tony Markatos:

Who was quoting Ed Yourdon: "Procedure is like dance - it defies [written]
> description". Therefore, use graphical techniques as much as possible;
> ideally, only use written text to supplement graphics.
>
> 6. Present the bigger picture of the procedure first (using graphics) - then
> filter down to the details (text). This is how the human mind processes
> procedural information - especially the male mind. A big problem with
> written-text-only procedural information is that, since it is so
> detail-level, it works against the way the mind naturally wants to see
> procedure - greatly increasing resistance to reading it.

I have problems with this "graphics good - text bad" approach.

In *certain* situations, *well executed* graphics are helpful but in many, many
other situations, they are simply noise.

When documenting hardware, they are often critical. For example, the setup
instructions for my new HP printer had no text at all and were easy to follow.

When documenting software, graphics are most useful when the interface has
certain challenges. For example, when the buttons have cryptic icons it's good
to show a picture because writing "click that thingy that looks like an upside
down martini glass" doesn't cut it.

However, many writers seem to equate graphics with raw screen captures and
believe that the more screen captures you have, the better.

Well, blech!

I often come across documentation with screen captures of every bleedin' form,
ok box and welcome screen. Worst of all, none of the images will have callouts
or annotations, the images are out of date (because the UI has changed) and the
printed images are too fuzzy to follow anyway. Not to mention, the simple stupid
redundancy of just repeating what the user is already looking at on the screen
without adding anything useful.

If by graphics you mean a carefully cropped, annotated or highlighted image that
draws my attention to key information, that's great. But I'll take a half page
of concisely written procedure over five jumbled pages of screen captures and
steps any day.

_____________________________________________________

Lee Hunter - Technical Editor & Information Architect

------ http://www.hum.com ------- 613-282-1904 ------
_____________________________________________________

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

ROBOHELP X5 - SEE THE ALL NEW ROBOHELP X5 IN ACTION!

RoboHelp X5 is a giant leap forward in Help authoring technology, featuring all new Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! View an online demo: http://www.macromedia.com/go/techwrldemo

---
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- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.



Follow-Ups:

References:
10 Things All Technical Writers Should Do: From: Andrew Plato
Re: 10 Things All Technical Writers Should Do: From: Dick Margulis
Re: 10 Things All Technical Writers Should Do: From: David Castro

Previous by Author: RE: Word to PDF problem
Next by Author: Re: Usability abuse? (Take II)
Previous by Thread: Re: 10 Things All Technical Writers Should Do
Next by Thread: Re: 10 Things All Technical Writers Should Do


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


Sponsored Ads