Facts vs. Instructions

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

Did the Corinthians ever write back?

Previous by Author: cancel subscription
Next by Author: Re: Complaining about Courier
Previous by Thread: Idea for a Writing Portfolio
Next by Thread: Re: Sidenote to "don't S...

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

Sponsored Ads