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.
> "R. Johnson" wrote
> Some technical documents could use an infusion of marcom,
> IMHO. Especially software manuals...
I agree too. It's often simple to combine both approaches, even in something
as short as an online help topic. Here's a typical outline with the benefits
and practical examples first, and the procedure second.
"Such-and-Such Task
You can [quickly, easily, always, often, any other adverb] do [such-and-such
task] with [product name]. You may want to do this if [most common scenario]
or [next most common scenario].... or: This can be handy when... or: This
can save you time if...
To do [such-and-such task]:
1. First step of procedure.
2. Second step...
X. Last step."
This approach orients the user to when and why they might need some feature
before plunging them into a series of mouse clicks. And the formatting makes
a clear division for people who just want to jump into the how-to.
Here's the same approach from the other angle: technical how-to information
embedded in a marketing document. This is from the script for a product demo
I was working on today... definitely a marketing document...
"The customer is always right!
That means even if you finish a design using one catalog, you may need to
change to a different catalog--or even a completely different
manufacturer--to keep your clients happy.
But with [product name], you won?t have to redraw your whole design.
Using Edit-Switch Items..."
and then it goes into the procedural stuff that follows the mouse clicks
around the screen.
So once again, a real-world scenario SHOWS the benefit of the feature before
it TELLS how to do it.
Another thing I always do in a technical manual is include a little section
at the start called "What is [Product Name]?" And then I stick in the 50-100
word product blurb to remind users why they or their company bought it in
the first place. That only takes a minute, and it makes for a much more
satisfying introduction to a manual.
===============================
Gordon Graham, Partner
Gordon & Gordon
----------------------------------------
(514) 488-1875
www.gordonandgordon.com
===============================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Order RoboHelp X3 and receive a $100 mail-in rebate, plus FREE
RoboScreenCapture, WebHelp Merge Module and iMarkupSoftware, for a total
giveaway value of $473! Order here: http://www.ehelp.com/techwr-l
Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at http://www.raycomm.com/techwhirl/special/contests/
Happy birthday to you, happy birthday to you, happy birthday 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.
