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.
I think my lament was that, what was so nice about the aftermarket manuals of the 90's, maybe the "golden age" of these things, is that you had the sense underneath it all that you were learning something much broader than the application at hand. I think we were learning how software and how computers worked, in general. You could pick up almost any of these books and you would still have that underlying sense.
I'm saying that's now gone, and has been gone for some time. Except locally, as you suggest, the educational aspect of tech writing is largely missing. I think that's one of the things that always gave it great flavor for me. I try to infuse that in current work, but it's no longer the "big mission" that I think was felt back then. I mean, who really cares about how an iPad works, or how any of the software on it works, as long as you can tell me how to do what I need to do with it -- how to "get going"?
Steve
-----Original Message-----
From: McLauchlan, Kevin [mailto:Kevin -dot- McLauchlan -at- safenet-inc -dot- com]
Sent: Tuesday, October 29, 2013 8:07 AM
To: Janoff, Steven; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Saying "why do this" (was RE: tableT woes (was RE: Using tables for content
[Nodding...]
If a system is pretty-much closed, or if the interface keeps the user well-protected from the inner workings, then you can just make your entire documentation a set of specific task instructions, and let the user figure out why, or when, or in what order they want to perform any tasks.
Not saying you should, but you can.
If a system is flexible and adaptable to a variety of situations, and has lots of configuration options, you can still give the user a bunch of task-specific instructions, but you'd be doing them a real disservice if you didn't include information about interactions and dependencies and implications.
I'll make up a two-dimensional example.
Say you had a new kind of mass storage. You can tell a customer to flip a software config button between "Balanced" setting and "Performance" setting.
Done.
But... the device can perform a limited number of write cycles to a given data location, before that location becomes unreliable, or stuck, or dead, and must be removed from visibility thereafter (meaning, device storage capability gets smaller with age and usage).
If config switch is set to Performance, it keeps data arranged so that it is quickest to access, at the expense of device lifetime. If it's set to Balanced, data storage is spread out according to an algorithm that maximizes the device lifetime by minimizing re-writes to any given location.
Perhaps the customer would like to know this, as well as how much performance difference can be expected, or how much lifetime difference can be expected, before they blithely click "Performance".
Perhaps they would like to be told it at the point where they are making the decision.
Some would suggest that such info is excess verbiage that just gets in the way of the customer who just wants to be told "Do this. Now do this. Done."
Either don't bother the customer with it at all, or put it in an appendix somewhere that they can search for if they are curious.
To me, the mentality that says "don't include explanation of options with instruction" is the same mentality that has SO many hover-text/tool-tips that repeat the name of the button or checkbox being hovered, with no additional info. [must suppress urge to kill...]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
