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.
> -----Original Message-----
> From: Peter Neilson
> To: Janoff, Steve
> Cc: techwr-l -at- lists -dot- techwr-l -dot- com
>
> Most cookbooks that tell how to make muffins got to great lengths
> explaining that the batter must be mixed no more than 25 strokes, and
> perhaps how novice cooks in their quest for perfection will go far
> beyond that number, making sure that every lump is wiped out. The sad
> result is that the muffins barely rise, and are mostly concave on top.
>
> My favorite recipe says it slightly differently:
>
> "Lumps will form. Ignore them."
>
> One paragraph. Two sentences. Five words. Will Strunk sleeps soundly.
Indeed, but if somebody is coming from a history of (say) meringue-making, they can go wrong with your instructions.
"Yeah, they are ugly. I dunno why. Lumps? Sure, I ignored them. WHA-A-AT!?! 25? Where do you get that? I gave it my usual 300 strokes. If you'd just told me 'mix just enough to wet the dry ingredients, no more than 25 strokes', I would have understood. Was somebody charging you extra for each word in your cookbook?"
Even cake batters usually get a minute or two with the electric mixer and are quite smooth before pouring, so it would be important to many people that you differentiate from what they are accustomed to.
Personally, I like a book like "Joy of Cooking" that includes all that category-explanatory stuff at the beginning of each section, with tips, tricks, hints, options, terms, then gives semi-minimalist instructions for each recipe. For any important caveats, they include a cross-ref within the recipe (See Cakes and Muffins p.461-62) which points back to the intro/explanatory pre-amble for the section.
In my own stuff, which is mostly WebHelp these days, I include a lot of explanatory text with the instructions, but I hide it as expanding/dropdown text, so those who don't care to see it don't need wade through it, but it's right there if you are hesitant about a decision or action. The dropdown/expansion hot words are differentiated by teal coloring (which looks a bit paler than the black text when viewed in monochrome), so maybe I have a bunch of color-vision-deficient readers mad at me.
Our field and tech-support people seem to like that the expandable supplementary stuff. I can't tell you if our customers like it, because I'm not allowed to talk with them, and they don't respond to "we'd like your feedback" or survey questionnaires. There is no budget for mock "user testing" - our users are technical people, in labs and IT back rooms and server farms, and our equipment and software are used in conjunction with networks and enterprise applications.
- Kevin
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
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-
