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.
""Richard Smith"" wrote...
>
> This shouldn't be very hard to communicate. All good docs share one
common
> thread. They contain the information users need. That's all.
>
> I've heard people say that things like typos, bad grammar, incorrect
usage,
> etc. all will cloud the credibility of a doc. That's a load of
you-know-what
> IMO. If I need to know the jumper settings to get board X to work, do I
care
> if it sounds like it's written by a third grader? No. Do I care if the
file
> is a PDF that makes me scroll three pages to the right? Not if it gets
the
> board working for me.
>
> Don't take that to mean the spelling and grammar don't matter. Take it
to
> mean that most users, while they will gleefully point such errors out to
> you, care most about finding the content they need. That's what makes a
> document good. Usability, readability, format, and style are all icing
on
> the info-cake.
You're going to make me cry Richard. I am so glad to hear somebody say
this. I remember the days when I would post such comments to TECHWR-L and
people would openly call me nasty names. Its good to see the "content
first" mindset is beginning to prevail.
I think the best way to benchmark a document is to hand it to a support
engineer who follows all instructions and ideas to the letter - like an
uninformed customer would do. All instructions should be verified, all
technical information proven correct. As for styles, fonts, and layout -
this is soooooooo subjective. If I had a dime each time somebody swore to
me they had the universal answer to readability...
Correct information is ALWAYS readable.
As for best practices...I can tell you one practice we throw around
Anitian.
When documenting something, you must answer the five golden questions:
1. What is it?
2. What does it do?
3. What is its purpose?
4. How does it work (or how does it do what it is supposed to do)?
5. Why is it relevant?
Andrew Plato
__________________________________________________
Do You Yahoo!?
Make international calls for as low as $.04/minute with Yahoo! Messenger http://phonecard.yahoo.com/
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.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.
