RE: Sloppy writing, sloppy thinking

Subject: RE: Sloppy writing, sloppy thinking
From: MList -at- chrysalis-its -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 28 May 2003 14:10:11 -0400


Andrew Plato [mailto:gilliankitty -at- yahoo -dot- com]
[...]
> It isn't that documents are "completely wrong," they're just
> not wholly
> accurate. Actually, what I see a lot more of these days is
> poorly focused
> documents. There is a tremendous amount of energy poured
> into sections of the
> document that describe simple commands and menus, and then
> detailed technical
> information is thrown into a poorly formatted appendix. A
> clear indication that
> the author did not understand the material, and was unwilling
> or unable to
> learn it.

Well, my technical detail isn't THAT poorly formatted (he said,
defensively <g>), but its location in appendices is in response
to direct requests from our Customer Support gang.

They thought that my first pass had too much info embedded
within the step-by-step stuff. Apparently, users don't
WANT to understand what they are doing or why they are
making a particular choice at a particular juncture. They
just want to follow some steps.
(USers just WANT to have FU-un. . . (who sang that?))

Of course, they sing another tune when their implementation
differs (as it must) from the plain vanilla. So, I nod to
both ends of the spectrum by keeping the "Do this" sections
lean and mean, but making liberal use of cross-references
to the why-and-how stuff, for those who need/want to know.

The SDK docs, on the other hand, have expository stuff and
lotsa tables and lists, and essentially no step-by-step bits.
(DeVELopers just WANT to make their OWN fun! (I can't get
the meter right on that chorus. . . .))

/kevin (sloppily)

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

Robohelp X3, from eHelp, lets you quickly and easily create
professional Help systems for all your Windows and Web-based
applications, including Net.

Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module.

Order RoboHelp today: http://www.ehelp.com/techwr-l

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



Previous by Author: RE: What does it mean to be technical?
Next by Author: RE: Drafts Back in Time
Previous by Thread: RE: Sloppy writing, sloppy thinking
Next by Thread: Re: Sloppy writing, sloppy thinking


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


Sponsored Ads