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.
Walter Crockett is <<... updating documentation on using scripts to run our
software from the DOS command line. The current documentation is not written
in a standard API form, and it is often difficult to tell which information
is supposed to be part of the script the user writes(a VB-type script), and
which is supposed to be included in the command. I have dealt with API
manuals before and found that the attitude among the engineers who spec them
out seems to be that anyone who can write scripts doesn't need any
hand-holding. However, I'd prefer to create a document so clear that even a
novice (with some understanding of programming languages) could learn how to
script the tool.>>
>From what you're saying, it sounds like most or all of the necessary
information is already present, and all you need to do is organize it
effectively. That being the case, a good first step would be to divide each
topic into three parts: the first explains the purpose of the command line
information, the second explains the command line options, and the third
explains the related script information. (Reorganize this as required to
match how users will actually write things; if the script comes first, start
with the script and conclude with the command line options. And so on.) If
it's not clear what belongs on the command line and what belongs in the
script, you'll need to either work with the developers to find out, or test
all the options yourself to make sure you've guessed right. Aim for the
first option as your main approach, but without being annoying about it;
even if you can puzzle things out yourself, you still need to develop a good
working relationship with the developers that proves you're willing to do
some work yourself (preliminary testing) but still want to collaborate with
them to produce good docs.
--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html
"How are SF writers like technical writers? Well, we both write about the
things we imagine will happen in the future!"--Sue Gallagher
A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe. http://ieeepcs.org/2001/
+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.comhttp://www.miramo.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.
