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: % 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? http://www.iuniverse.com/media/techwr
---
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.
