RE: Documenting the user interface

Subject: RE: Documenting the user interface
From: Melissa Nelson <melmis36 -at- hotmail -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 11 Jan 2007 10:50:34 -0500

I agree that this is a "know your audience" type thing. I documented the same program recently for three different audiences, who each use it in a different way. For one audience it was very much a hand holding document, and for the other two I was told to presume that they knew this or knew that and document from that point. It was an interesting project to say the least. :)

Melissa





> Date: Thu, 11 Jan 2007 08:46:55 -0700> From: richard -dot- combs -at- Polycom -dot- com> To: mike -at- writestarr -dot- com; techwr-l -at- lists -dot- techwr-l -dot- com> CC: > Subject: RE: Documenting the user interface> > Mike Starr wrote: > > > However, to leave users twisting in the wind, resorting to > > "exploring and learning", because there is no reference > > documentation is unconscionable. > > Every button, checkbox, radio button, drop-down list box, > > etc. in a user interface needs to be explained somewhere in > > the documentation set. Not only that but it must be easy for > > the user to find that explanation when he/she needs it.> > Every etc. needs to be explained, or users twist in the wind? Nonsense.> That approach leads to at least two bad consequences: > > -- Almost no one uses that 400-page manual because they get sick of> wading through > useless information like "The First Name field is where you enter the> user's first, or given, name. The maximum length is 30 characters. The> valid characters are the letters a through z, A through Z, ..."> > -- The minority of users who actually _do_ use a manual like that have> their innate timidity, passivity, and dependency reinforced, instead of> being encouraged to become active participants in the learning process.> Then, the tiniest mismatch between the interface and the hand-holding> documentation upon which they've come to depend throws them for a loop. > > Admittedly, "Know your audience!" applies, and there are products and> audiences that call for a very thorough, newbie-oriented approach. But> 90% of the time, this is over-documenting. People do it because it keeps> them busy, it's a CYA thing, and it's easier than the difficult process> of determining what's really important and how best to present it. > > "It's my opinion and it's very true."> > Richard> > > ------> Richard G. Combs> Senior Technical Writer> Polycom, Inc.> richardDOTcombs AT polycomDOTcom> 303-223-5111> ------> rgcombs AT gmailDOTcom> 303-777-0436> ------> > > > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^> > WebWorks ePublisher Pro for Word features support for every major Help > format plus PDF, HTML and more. Flexible, precise, and efficient content > delivery. Try it today! http://www.webworks.com/techwr-l> > Create HTML or Microsoft Word content and convert to Help file formats or > printed documentation. Features include single source authoring, team authoring,> Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList> > ---> You are currently subscribed to TECHWR-L as melmis36 -at- hotmail -dot- com -dot- > > To unsubscribe send a blank email to > techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com> or visit http://lists.techwr-l.com/mailman/options/techwr-l/melmis36%40hotmail.com> > > To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com> > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit> http://www.techwr-l.com/techwhirl/ for more resources and info.> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


Follow-Ups:

Previous by Author: RE: A good beginning to the week
Next by Author: PDF's to PDAs
Previous by Thread: Re: Documenting the user interface
Next by Thread: RE: Documenting the user interface


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


Sponsored Ads