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.
Beth reports: <<I am new to unix and have been asked to document custom unix
utilities for our system administrators.>>
"Our" suggest that this is in-house documentation, or that you at least have
the possibility of some contact with the sysadmins. That being the case,
your first step should be to book some time with a representative sampling
of these people to find out what kind of documentation they're accustomed to
using, how they invoke it (if online), plus what they like and dislike about
this form of documentation.
Use that as a starting point for your design: sticking with what they
already know how to use has significant advantages, particularly if you can
use their likes and dislikes to do a better job of using that medium.
<<Does anyone have any info for documenting custom unix utilities or where I
could go for ideas or a place to start?>>
"Man" pages (short for manual, not alpha male geeks <g>) seem to be the
standard for Unix, but it's been so long since I've used Unix from the
command line that I won't comment further--have a look at the man pages on
the systems you're documenting for typical examples of style conventions and
what to expect. Hopefully some other techwhirlers can provide the details I
can't provide. (Or wait a few months until I've had time to go spelunking in
the depths of OS-X on my new Mac. <g>)
<<The administative tools for the application I support is basically unix
custom utilites, each with separate functions. Some administrative tasks
involve going into more than one utility to perform a task, so I'd like to
document it by utility. (Good idea?)>>
I'm not familiar with Unix utilities, so with that caveat in mind, I don't
see any reason why you couldn't follow the same approach used with Windows
or Mac utilities: First, build as much assistance as possible into the
interface itself (if a GUI); second, try to provide context-sensitive help
using whatever help facilities the utilities can invoke. I imagine that a
true utility (rather than a one-line command with multiple switches) could
be written in the form of a wizard with a little cooperation from the
developers; for example, the user would type the command, then if no
switches or options were included, it would ask the user to respond yes or
no (or enter a value) in response to a series of questions.
The problem is that you noted that the utilities can be called from both the
GUI (which lets you build affordances--clues--directly into the interface
and permits the use of context sensitivity) and the command line. Can't
comment on the command line aspect, other than to suggest man pages again.
Hope someone else can be more specific!
That's only a starting point, though, since all you're doing here is
explaining the features of the interface or command-line options. You
mentioned five separate utilities, and their functions. To complete your
documentation, create some kind of task-based documentation. Something along
the lines of "here are the tasks you can perform: [insert list] and here's
the utility you need to use to perform that task [insert list matching the
list of tasks, perhaps as a table]. Click here [online] or turn to page X
[print] to display the help for each of these tasks". Then provide
procedural help for each task, with explanations of how that task relates to
the other tasks and their respective utilities.
--Geoff Hart, ghart -at- [delete]videotron -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"Wisdom is one of the few things that look bigger the further away it
is."--Terry Pratchett
RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4
---
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.
