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.
Subject:RE: You Don't Need to Know How From:"SM Rush" <sellar -at- apptechsys -dot- com> To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Thu, 26 Jul 2001 12:53:49 -0700
Here are three reasons why knowing more is better, and why using an
interface as a guide to gather information about the product is inadequate
(at the very least).
Bottom line for those in a hurry: understanding the "how" will help you
more easily and accurately understand the "what", and in fact may be the
only way you can get to an accurate understanding of the "what".
[I'll stick with interface examples here (a database product designed for
the average user); it's understood if you're documenting technology or a
product with no front end you've got to know more. And I'll stipulate that
extremely simple products (i.e. one-task wonders) probably don't need a lot
of know-how.]
1. You must be able to ask the developers the right questions to get correct
*and* complete answers. Programmers, just like all of us, answer the
questions they're asked; if they anticipate what information we (and users)
need to know and lay it all out for us, they're better at tech comm than we
are. (Note: this is not a matter of gaining respect so they'll talk to you,
it's a matter of eliciting the pertinent facts.)
Example:
Q: What do the features "Build Index" and "Drop Index do?
A: "Build" creates the index file and builds the index. "Drop" deletes the
index file.
Q: Why would someone want to drop or build an index?
A: They should rebuild the index if they've changed the structure or
imported data from lots of different sources.
(So much for the bare minimum. Here's one you really need to be asking.)
Q: Do you have to drop the current index before you build a new one?
A: Sometimes. By the way, when they build the index it also redoes word
analysis.
Q: Huh?
2. Interfaces are not perfect. Programmers make assumptions about what users
know, they organize features incorrectly or not at all, they use terminology
incorrectly and inconsistently. They group features together because they're
related technically regardless of whether they have any practical
relationship. Sometimes they're designing with the next version in mind.
Knowing the context of the product will help you understand the problems,
help users work around them, and maybe even get them fixed before it ships.
Example:
In a db product I'm working on, db design features are all mixed up with db
viewing features. The edit menu contains the following submenus: New,
Items, and Queries. New lets you create any of 4 different types of "items".
Items lets you view or design only one of the possible "items". Queries lets
your save or load a query.
Q: Huh?
3. You often have to provide structure beyond merely a sequence of
instructions to accomplish a single task. This is related to #2 above,
dependent on programmer assumptions and decisions. This is one of those
situations where the resulting instructions look like a no brainer, but
actually took a lot of thought and questioning to put together.
Example:
Q: So how does the user create a new database?
A: See that feature there? "New Database"? That creates all files they'll
need.
Q: Ah. But then they need to create the database structure, right?
A: Right here. "Import Data." That brings up the modeling tool.
Q: But...what if they just want to create a structure, not import data?
A: Well, they can in the modeling tool, but most users will create a model
to fit the data they're importing.
Q: So how do you create a db struct..er, model?
A: Here, let me show you. We just added drag and drop, so it's really easy
for the user. See, here I just drag from this list here, and drag this from
over here, create a link between the two, and voila, a new database!
Q: Huh? Where did that list come from?
The resulting documentation looks something like this:
Building a database:
Step 1: identify the data source (one lengthy procedure)
Step 2: create a model (three procedures minimum)
Step 3: import data (two procedures minimum)
Note: lots of times this type of big job is handled using a wizard. Lets
see a show of hands from those who've had to document wizards that made the
process more confusing than without them?
BTW: just to get in on the simple appliance, simple documentation act.
Just suppose that certain properties of microwave are not known world wide.
You can write up how to set the timer, how to defrost, how to cook popcorn.
But what if the technical geniuses in the lab never bothered to mention what
happens when you leave the aluminum foil on? Wouldn't a familiarity with
microwave technology be useful here?
Do you really want to base your documentation on simply asking the
developer:
Q: So, is there any way a user could completely hose their [data, hard
drive, home, nuclear reactor]?
Anybody who's read this far gets a big chocolate smooch from me...
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com
Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com
---
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.