Saying "why do this" (was RE: tableT woes (was RE: Using tables for content

Subject: Saying "why do this" (was RE: tableT woes (was RE: Using tables for content
From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
To: "Janoff, Steven" <Steven -dot- Janoff -at- ga -dot- com>, "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 29 Oct 2013 11:07:05 -0400


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.

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.


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

Learn more:


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


Previous by Author: tableT woes (was RE: Using tables for content
Next by Author: Re: MIT Technology Review - piece on writing tools
Previous by Thread: RE: TableT woes (as opposed to table woes)
Next by Thread: RE: Saying "why do this" (was RE: tableT woes (was RE: Using tables for content

What this post helpful? Share it with friends and colleagues:

Sponsored Ads