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.
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...]
-----Original Message-----
From: Janoff, Steven [mailto:Steven -dot- Janoff -at- ga -dot- com]
Sent: October-28-13 7:38 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com; McLauchlan, Kevin
Subject: RE: tableT woes (was RE: Using tables for content
Yes, I agree, and well, yes, this is probably an old notion, but it seems like there's very little support for backstory or the "why" these days, and everything is about getting the user on their way. Maybe that's the fault of minimalism, who knows.
All I remember are those big, fat, luscious aftermarket manuals of the 90's, and how much fun they were to read. I could sit with one of those for hours. I really felt like I was learning something. Nowadays I don't really feel like I'm learning anything by using software. Maybe that's just because we've all caught up, and the only thing left is to use the tool for what it's intended for.
But I've heard this lament before. Tech writing is really a different beast from what I remember. I guess the computer field was still young and we were still learning how computers worked. Now we know how they work, we know how software works, it's just, what the heck can you do with it.
Steve
[snip myself...]
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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
