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:
>
> > Unfortunately, they can't tell me exactly WHY the documentation
> > is so good.
>
> This shouldn't be very hard to communicate. All good docs share one common
> thread. They contain the information users need. That's all.
That is by no means all. If you said "They make the information users need
readily accessible", then I'd agree, but just comtaining the info users
need is not nearly enough.
Organisation is essential:
The information doesn't just have to be there, it must be organised so it
makes sense and things are findable.
Indexes and cross-references are vital:
Users often need to find only some small bit of info. Good docs make it
possible to do this efficiently.
Format is important:
For example, you might deliver exactly the same info in several paragraphs
of complex text or in an easily-scanned table.
> 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.
I'd say having the info is a basic requirement. Without it, the doc is
rubbish. For a good doc, you need usability. Anything beyond that is
icing.
*** 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.
