TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Book: What makes a great user manual? From:Chris Morton <salt -dot- morton -at- gmail -dot- com> To:"techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 16 Jan 2017 12:03:58 -0500
Here is an example of what I'm up against:
For the purpose of these procedures, it is assumed that the patient remains
in place during all these procedures, although the patient can be removed
at any point in this process when it is safe to do so.
And:
The gizmo needs to be rotated into storage position for proper storage. To
release the gizmo,
actuate the unlock lever by lifting the lever up. Rotate the gizmo 180
degrees until it locks into
position.
WARNING: The gizmo needs to be rotated into storage position for proper
storage and transportation.
*In order to drive a car, you must insert the key into the ignition, Insert
the key into the ignition so as to be able to drive the car. Once you have
done so, you can then drive carâbut only after you have inserted the key
into the ignition. Now go ahead and insert the key into the ignition so you
can drive the car.*
And yet my client doesn't want to make (what it considers) "grammar"
changes. Judging from a late Friday email exchange, it's become evident
that client has never even read their own freakin' manual. It certainly
reads like it was outsourced, or at least written by an ESL engineer who
perhaps volunteered for the assignment.
(And I mean no offense to those who are either an engineer or ESL, so
please don't take any.)
On Mon, Jan 16, 2017 at 11:37 AM, Slager Timothy J <
Timothy -dot- Slager -at- dematic -dot- com> wrote:
> If "they obviously work for many" that makes (some of) them pretty good. I
> suppose the question is whether there is a standard that bumps the "work
> for many" into the "works for most" category. ("Works for all" is one of
> those typically unachievable goals worth striving for.)
>
> I liked the advice in the Forbes article to contact the manufacturer and
> complain. But complaints too can lead to poor design--unless there are
> enough of them to confirm that something is actually insufficient, wrong,
> or confusing. So often one person's good is another person's bad. Making a
> change based on a few complaints may cause that typical problem, in
> software terms, of adding a bug while removing another. On the other hand,
> failing to include how to add string to a trimmer seems like a gross
> oversight.
>
> I'm interested too in knowing what are the essentials of a good manual. I
> suspect it is a compromise at best. If it includes what some really like,
> it should do so in a way that isn't too off-putting to those who dislike
> that sort of thing. If it has to include lots of warnings, it should make
> it easy to find the other information. If it has too many pictures, they
> should be good ones. If it has too many words, they should be clear.
>
> I'm afraid that if I finally figured out exactly what makes a good manual,
> by the next year the recipe would no longer apply. So the quest
> continues--as it should.
>
> tims
>
> -----Original Message-----
> From: techwr-l-bounces+timothy -dot- slager=dematic -dot- com -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+timothy -dot- slager=dematic -dot- com -at- lists -dot- techwr-l -dot- com]
> On Behalf Of Chris Morton
> Sent: Monday, January 16, 2017 11:06 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: Re: Book: What makes a great user manual?
>
> Thanks, Tim, but my question isn't about *Dummies* books. They obviously
> work for many and that's great. I was turned off by a volume on TCP/IP I
> bought years ago.
>
> I do a fair amount of writing. Outside of the technical realm, much of
> what I write includes humor here and there, as witnessed on this and other
> forums in which I participate. So I enjoy a good bit of humor. But while
> growing up, I never found The Three Stooges, Green Acres or Gomer Pyle to
> be funny enough to keep me engaged. For me, that level of
> thunk-over-the-head humor doesn't cut it.
>
> So... back to the original question....
>
> Chris Morton
>
>
>
> â Substantive Editing â Technical Writing â Proofreading
> â Marketing Expertise â Mentoring Click to <
>http://t.sidekickopen68.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nM
> JN7t5XYgdnqQxW7fsH3H4XrddKW1pNgV-56dMhqf2Q-c6C02?t=https%3A%
> 2F%2Fwww.linkedin.com%2Fpub%2Fchris-morton%2F2%2F166%
> 2F6ba&si=6020636811198464&pi=fa4629a9-bd82-48f9-f5b3-6b9bd993b242>
>
>
> On Mon, Jan 16, 2017 at 10:48 AM, Slager Timothy J <
> Timothy -dot- Slager -at- dematic -dot- com> wrote:
>
> > I've used a few Dummies books. One I thought was amazingly well done,
> > and another was pretty bad. Both of these were on programming, which I
> > knew next to nothing about.
> >
> > tims
> >
> > -----Original Message-----
> > From: techwr-l-bounces+timothy -dot- slager=dematic -dot- com -at- lists -dot- techwr-l -dot- com
> > [mailto:techwr-l-bounces+timothy -dot- slager=dematic -dot- com -at- lists -dot- techwr-l -dot- com
> > ]
> > On Behalf Of Chris Morton
> > Sent: Monday, January 16, 2017 10:40 AM
> > To: techwr-l -at- lists -dot- techwr-l -dot- com
> > Subject: Re: Book: What makes a great user manual?
> >
> > I can't stand *Dummies* books, Craig. Usually the humor is at the Adam
> > Sandler/Mr. Bean level. Not my cuppa.
> >
> > Chris Morton
> >
> >
> >
> > â Substantive Editing â Technical Writing â Proofreading
> > â Marketing Expertise â Mentoring Click to <
> > http://t.sidekickopen68.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nM
> > JN7t5XYgdnqQxW7fsH3H4XrddKW1pNgV-56dMhqf2Q-c6C02?t=https%3A%
> > 2F%2Fwww.linkedin.com%2Fpub%2Fchris-morton%2F2%2F166%
> > 2F6ba&si=6020636811198464&pi=96a12667-7627-44fb-9750-a7bfe0e453e7>
> >
> >
> > On Mon, Jan 16, 2017 at 10:38 AM, Cardimon, Craig
> > <ccardimon -at- m-s-g -dot- com>
> > wrote:
> >
> > > I always liked the Dummies books as launching pads. Great just to
> > > get you started.
> > >
> > > Anyone else use Dummies as starting points?
> > >
> > > ~Craig
> > >
> > > -----Original Message-----
> > > From: techwr-l-bounces+ccardimon=m-s-g -dot- com -at- lists -dot- techwr-l -dot- com [mailto:
> > > techwr-l-bounces+ccardimon=m-s-g -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf
> > > techwr-l-bounces+Of
> > > Chris Morton
> > > Sent: Monday, January 16, 2017 10:35 AM
> > > To: techwr-l -at- lists -dot- techwr-l -dot- com
> > > Subject: Re: Book: What makes a great user manual?
> > >
> > > Specifically I'm interested in a somewhat breezy book (but not like
> > > *Dummies*) that clearly explains the problems the problems that can
> > > ensue with a manual that is poorly written/laid out.
> > >
> > > Chris Morton
> > >
> > >
> > >
> > > â Substantive Editing â Technical Writing â Proofreading
> > > â Marketing Expertise â Mentoring Click to <
> > > http://t.sidekickopen68.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9nM
> > > JN7t5XYgdnqQxW7fsH3H4XrddKW1pNgV-56dMhqf2Q-c6C02?t=https%3A%
> > > 2F%2Fwww.linkedin.com%2Fpub%2Fchris-morton%2F2%2F166%
> > > 2F6ba&si=6020636811198464&pi=7db9504b-239d-4442-cc97-f40fe7da56e4>
> > >
> > >
> > > On Mon, Jan 16, 2017 at 10:13 AM, Chris Morton
> > > <salt -dot- morton -at- gmail -dot- com>
> > > wrote:
> > >
> > > > Considering the following (as well as usability works by Steve
> > > > Krug), I'm wondering if there is a similar volume that takes a
> > > > good look at user manuals. Your recommendations welcome, although
> > > > each should be easy read in keeping with what Redish and Krug are
> > > > conveying. (I have a low tolerance for high-brow studies written
> > > > by
> > > > PhDs.)
> > > >
> > > > *Letting Go of the Words: Writing Web Content that Works* by Ginny
> > > > Redish
> > > >
> > > > "Web site design and development continues to become more
> > sophisticated.
> > > > An important part of this maturity originates with well-laid-out
> > > > and well-written content. Ginny Redish is a world-renowned expert
> > > > on information design and how to produce clear writing in plain
> > > > language for the web. All of the invaluable information that she
> > > > shared in the first edition is included with numerous new examples.
> > > > New information on content strategy for web sites, search engine
> > > > optimization (SEO), and social media make this once again the only
> > > > book you need to own to optimize your writing for the web."
> > > >
> > > > Thanks
> > > >
> > > > Chris Morton
> > > >
> > > >
> > > >
> > > > â Substantive Editing â Technical Writing â Proofreading
> > > > â Marketing Expertise â Mentoring Click to
> > > >
> > > > <http://t.sidekickopen68.com/e1t/c/5/f18dQhb0S7lC8dDMPbW2n0x6l2B9n
> > > > MJ
> > > > N7
> > > > t5XYgdnqQxW7fsH3H4XrddKW1pNgV-56dMhqf2Q-c6C02?t=https%3A%2F%2Fwww.
> > > > li
> > > > nk
> > > > edin.com%2Fpub%2Fchris-morton%2F2%2F166%2F6ba&si=6020636811198464&
> > > > pi
> > > > =2
> > > > 0d48203-2891-4cb8-fd95-abe81b7e7276>
> > > >
> > > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > Visit TechWhirl for the latest on content technology, content
> > > strategy and content development | http://techwhirl.com
> > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > >
> > > You are currently subscribed to TECHWR-L as ccardimon -at- m-s-g -dot- com -dot-
> > >
> > > To unsubscribe send a blank email to
> > > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> > >
> > >
> > > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > > http://www.techwhirl.com/email-discussion-groups/ for more resources
> > > and info.
> > >
> > > Looking for articles on Technical Communications? Head over to our
> > > online magazine at http://techwhirl.com
> > >
> > > Looking for the archived Techwr-l email discussions? Search our
> > > public email archives @ http://techwr-l.com/archives
> > >
> > > Information contained in this e-mail transmission is privileged and
> > > confidential. If you are not the intended recipient of this email,
> > > do not read, distribute or reproduce this transmission (including
> > > any attachments). If you have received this e-mail in error, please
> > > immediately notify the sender by telephone or email reply.
> > >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Visit TechWhirl for the latest on content technology, content strategy
> > and content development | http://techwhirl.com
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as Timothy -dot- Slager -at- dematic -dot- com -dot-
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources
> > and info.
> >
> > Looking for articles on Technical Communications? Head over to our
> > online magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions? Search our
> > public email archives @ http://techwr-l.com/archives
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as Timothy -dot- Slager -at- dematic -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
>http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
