RE: Documentation Deliverables for Complex Scenario

Subject: RE: Documentation Deliverables for Complex Scenario
From: "Connie Giordano" <connie -at- therightwordz -dot- com>
To: <dvora -at- tech-challenged -dot- com>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 1 Jul 2009 19:24:03 -0400

Deborah,

Spend some time on the true end goal of your documentation... and that is
NOT how to use the software. People use software to accomplish
something--take an action, calculate an invoice, approve an activity, submit
a budget, evaluate an employee, pull inventory, track vacation days, modify
a photo, lay out an ad, schedule a delivery etc. If they can find a way to
accomplish it without the software, a good portion of them probably will.
Not everybody has the geeky tendencies we do. When you know what the users'
real goals are, the structure, medium and content of the documentation
should become much easier to define.

Will the theory behind the software actually help them do their jobs, meet
their quotas, avoid a layoff, or get a promotion? If so, present it in the
context of how the software supports doing their job. If not leave it for
reference material for the relatively small percentage that will actually be
interested. Are there different groups of users who will use pieces of the
software to do a certain type of job, while others may never use or even
have access to it? Then consider organizing your documentation around the
type of user e.g: Business Manager for Office Managers, Business Manager
for HR, Business Manager for Line Supervisors, etc. Role-based
documentation has some distinct advantages. You can still build procedural
topics once for reuse wherever needed (how to change your password for
example), procedural topics related to the role (how to requisition office
supplies) and create more conceptual topics that may relate only to the whys
of using this function to perform an Office Manager duty. This approach is
more complex to design, but I find that it provides huge value to the user,
client management, and your own sales and marketing folks who can demo
software with "help that's actually helpful" (I actually had a product
manager and a VP tell me that's what they did). This also helps bring
clarity to some of the other critical mechanics, like building effective
TOCs and useful indexes.

You might like to think of it as a BA approach to structuring
documentation... it could help explain why I like the approach so much.

It's a pretty large challenge, but I'm betting you're up to it!

Regards,


Connie P. Giordano
The Right Words, LLC
Communications & Information Design

http://www.therightwords.com
http://www.cowbellchallenge.org
http://www.uscup.net
connie -at- therightwords -dot- com
 
(704) 540-9985 (office)
(704) 957-8450 (mobile)
 
"It's kind of fun to do the impossible." - Walt Disney




-----Original Message-----
From: techwr-l-bounces+connie=therightwordz -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+connie=therightwordz -dot- com -at- lists -dot- techwr-l -dot- com] On
Behalf Of Deborah Hemstreet
Sent: Wednesday, July 01, 2009 6:14 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Documentation Deliverables for Complex Scenario


Firstly,

Thank you all for your quick responses. I love Dilbert anyway, and
Peter's response was my gut reaction. I talked with the client, and
hence my email to you all!

I like Kathleen's approach. Right now there 7 books for different
aspects of working the SW... I prefer the TWO book approach, with theory
and How to... and good linking, related topics, etc. between them all.

Geoff has some good points. I may try to discuss working on the GUI now,
and see if they can implement "Smart" help for each page... that would
be ideal (I think). However, I am doubtful that the client will be open
to any touching of the GUI at this point in time, but I could be wrong.

Having said that... I am wondering if there are any other
thoughts/ideas/out of the box ideas that anyone has.

Thanks again. Talk with you later.

Deborah
http://www.tech-challenged.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 connie -at- therightwordz -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/connie%40therightwordz.co
m


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



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


References:
RE: Documentation Deliverables for Complex Scenario: From: Brian.Henderson
Re: Documentation Deliverables for Complex Scenario: From: Deborah Hemstreet

Previous by Author: RE: Calling All RoboHelp Experts!
Next by Author: RE: Am I Off the Wall?????
Previous by Thread: Re: Documentation Deliverables for Complex Scenario
Next by Thread: Documentation Deliverables for Complex Scenario?


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


Sponsored Ads