RE: Examples of Great Software/Web-based User Guides

["Boudreaux, Madelyn (GE Healthcare, consultant)" <MadelynBoudreaux -at- ge -dot- com>]

Laura Lemay wrote:
>There was also at one point in the early/mid 90's a minor movement 
>especially in small companies toward extremely informal conversational 
>documentation, with the idea that "no one reads the docs" could be 
>counteracted by writing funny, interesting documentation. 

This is interesting to me. Clearly, in some industries, this is true.
For example, my partner's sound recording gear comes with well-written
yet extremely amusing documentation, and it works -- he reads it, and
enjoys it, and shares it with me. 

In a former position, I documented databases that ranged from medicine
to gas and oil industries to math to art history, and one of my favorite
parts of the job involved providing search strategies that showed how
Boolean searches behaved and that returned actual articles from the
databases. While I didn't make them amusing (usually), I did strive to
make them interesting as well as meaningful: "oil paint and sculpture"
is not especially meaningful (which I know), but it was a struggle to
come up with meaningful math examples. At first I hated this task, but
once I realized I could pretty much put anything in (watching out for
hot-button issues, of course), I came to love it. 

How much "interestingness" should a document include (accepting that my
"fascinating" is someone else's snoozefest)? How dry is too dry?
Interesting real-world examples really help ME stay on task, and I'm no
unique snowflake. 

To tie in to an earlier point, I've been beating my head against the
help in Flare, and while I can't find answers to some of my questions --
which I suspect are esoteric for most users, which doesn't make them any
less important to ME -- I DID enjoy the tutorial using fairy tales. 

- Madelyn
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Free Software Documentation Project Web Cast: Covers developing Table of
Contents, Context IDs, and Index, as well as Doc-To-Help  
2009 tips, tricks, and best practices.
http://www.doctohelp.com/SuperPages/Webcasts/

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control! http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -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%40web.techwr-l.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/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat