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.
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
"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.
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-
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-
