RE: Inventive Documentation [was Re: Let's hear it for Connie...( or, go and do likewise...)]

["Giordano, Connie" <Connie -dot- Giordano -at- FMR -dot- COM>]

Megan,

Oh thank you for hearing my plea to find out who's doing cool new stuff!

-How about "coaches" inside the application?  what would trigger a coach to
provide a hint, or an animated demo of how to do it? who builds what pieces?
How do you QA it?
-SVG (Scalable Vector Graphic) diagrams and text linked to workflow enabled
functionality? can you trigger an explanation by clicking on a spot in a
diagram?  Is it technically feasible to build SVGs into XML/.NET
applications?  Will my developer teammates just roll their eyes?

These are two areas that I'm trying to find time to research and would love
to hear any war stories on how to plan, design and deliver.  I work with
eight rather complicated financial software packages, and this is an area
that I think could be of great benefit to our user bases.  However, being
the lone writer, I don't have enough hours in the day, so if anyone has
experience with either of these, let us know!

Connie Giordano

Who, by the way, is blushing from the kudos...thanks Charles!

Connie P. Giordano
Senior Technical Writer
Advisor Technology Services
A Fidelity Investments Company
704-330-2069 (w)
704-330-2350 (f)
704-957-8450 (c)
 
 "You can't build a reputation on what you are going to do."  - Henry Ford 


-----Original Message-----
From: Megan Golding [mailto:mgolding -at- secureworks -dot- com]
Sent: Thursday, June 27, 2002 8:56 AM
To: TECHWR-L
Subject: Inventive Documentation [was Re: Let's hear it for
Connie...(or, go and do likewise...)]



Sometime Tuesday, Chuck Vermette posted a great comment from Connie
Giordano:
> <<<Over 2 1/2 years I have patiently and repeatedly explained that there
> are new and better ways to support the product than just a manual. Then
> I deliver those new and better ways on time and on budget.  

Connie's "new and better ways" got me to thinking -- what are some
inventive ways you've used/seen to document something?

In my time, I've seen and used any or all of the following:

1. A Wiki site (see http://twiki.org for the particular type I use). Its
a web site that anyone can edit. This distributes documentation
responsibility to an entire team. In my case, I've gotten developers to
write a lot of the internal docs simply by providing them this
easy-to-use place to write. Wiki, IMHO, is best for informal, internal
documentation. 

2. The Linux Documentation Project (see http://www.tldp.org). Their
HOWTO's, written mainly by amateur writers (read: developers and users
of the software), get to the point quickly and are highly focused. I
appreciate a quick, "How do I do this?" document.

3. Training. No joke. Let's face it, people don't like to read manuals
(at least not in the US). A Washington Post article, publicized on this
list recently, and at
http://www.washingtonpost.com/ac2/wp-dyn?pagename=article&node=&contentId=A8
275-2002May25&notFound=true, talks about not reading the manual. I think
that training is an excellent substitute. Unfortunately, its not very
efficient at reaching as many people with as few resources as written docs.
Web-based training makes strides in that direction.

4. The one-page Quick Start Guide. I love this thing! I first saw them
with new computers where the guide is poster-sized, very colorful, and
virtually all visual. I've applied the concept to several products with
varying degrees of success. Very innovative solution to the "Won't read
the manual" problem I mentioned in #3, above.

Anyone else?

Meg

-- 

Megan Golding (mgolding -at- secureworks -dot- net)
SecureWorks, Inc.

Make your life a mission - not an intermission.
         -- Arnold Glasgow




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
Save $600: Create great-looking Help files and software demos with
RoboHelp Deluxe. Get RoboHelp and RoboDemo - our new demo software - for one
low price. OR Save $100 on RoboHelp Office in June with our mail-in rebate.
Go to http://www.ehelp.com/techwr-l
---
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.