RE: % of Users Who Read Software Documentation

Subject: RE: % of Users Who Read Software Documentation
From: Matthew Horn <mhorn -at- macromedia -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 7 Feb 2002 09:27:23 -0500

Jane writes:

>> Make it enjoyable to read...Make them *want* to read the manual.

I would love to do this, but for a couple of problems:

- Translation..... Part of making something fun to read is using the language to evoke images and emotions from your readers. But my editor (and most tech editors) doesn't like idioms or cute phrases.

For example, I tried titling a section "Test-driving your JDBC drivers", and it was flagged because the translators would have a hard time with it. Also, I wrote "The controller in MVC acts like a traffic cop for request and response objects." That was flagged because it uses American slang.

- Ambiguity..... The potential to be misunderstood is increased when you write creatively within a technical manual.

- Dumbing-down..... Readers might regard "fun and accessible" writing as a sign of weakness in the docs. They might start thinking of your manual as a Dummies book. Especially power users who want all the command-line switches and none of the cute stuff.

I think the most important thing about a technical manual is a good index. Noone reads it front to back, IMO. My brain says stick to the facts, ma'am.

Do you have any examples of tech writing that is interesting AND informative AND passed the inspection of a tech editor?

Matthew Horn
Sr. Technical Writer
< m a c r o m e d i a >

Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for?

Have you looked at the new content on TECHWR-L lately?
See and check it out.

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 for more resources and info.


Previous by Author: RE: Dreamweaver training question
Next by Author: RE: here's my dilemma
Previous by Thread: RE: % of Users Who Read Software Documentation
Next by Thread: RE: % of Users Who Read Software Documentation

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

Sponsored Ads