RE: How much do people need to be told in documentation.

Subject: RE: How much do people need to be told in documentation.
From: "Stuart Rogers" <srogers -at- phoenix-geophysics -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 17 Sep 2001 13:26:29 -0400

IMO, if a person *has* an e-mail address, then they know how to type it,
and a clear instruction with a simple example will do ("Type your
complete e-mail address, in the form jdoe -at- foobar -dot- com"). Adding a lengthy
dissertation on the format definition is POINTY-HEADED excess and will
only irritate and confuse users.

The Microsoft Manual of Style for Tech. Pubs. Includes a discussion of
mouse vs. keyboard procedures (p. 219 of 2nd ed.), saying you have a
choice (generally made by the team lead) of mouse-only ("click,"
"double-click," "point to"), combined mouse and keyboard without
distinguishing between them ("select", "choose"), or separate mouse and
keyboard actions, explaining first the mouse method and then the
keyboard method. They conclude with: "The trend is to document with
mouse-only actions..."

I think the mouse-only method is safest and most consistent. It's our
job to make sure users *can* use the software, not necessarily to make
them power-users. Those who are capable of or interested in becoming
power-users have probably already figured out the advantages of keyboard
shortcuts in their other app's, and will learn them in yours.

Good luck,

Stuart Rogers
Technical Writer
Phoenix Geophysics Limited
mailto:srogers -at- phoenix-geophysics -dot- com


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

A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.com http://www.miramo.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.


Follow-Ups:

Previous by Author: Re: To utilize or not to utilize
Next by Author: Best settings for screen captures?
Previous by Thread: RE: How much do people need to be told in documentation.
Next by Thread: RE: How much do people need to be told in documentation. - Resolution


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


Sponsored Ads