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:Facts vs. Instructions From:Glen Accardo <glen -at- SOFTINT -dot- COM> Date:Mon, 6 Jun 1994 11:28:25 CDT
Instructions or concepts?? hmmmmm. The manuals I write are for sys admin
types, telling them all the gory details of our software: lots of concepts
and a few instructions. I often use sentences like "SQLASSIST requires a
valid terminfo entry." Granted, I define "valid" a bit more, and I define
what happens if there isn't a valid entry, but I don't give any procedural
way of _recognizing_ the problem.
Also, I don't want to document how to fix the problem. It's easier for
us to build the required files than to document how to do it. So, the
"solution" to the problem is "build your own terminfo entry using XXXX as
an example or call us for assistance."
Should I go with a more procedural way of handling the problem? I don't think
there are legal problems here, but with an ignorant sys admin I could
certainly see the "A requires B" sentence being a bit vague or incomplete.
------------
glen accardo glen -at- softint -dot- com
Software Interfaces, Inc. (713) 492-0707
Houston, TX 77084
