Re: Documenting unix utilites
Since Unix utilities are normally documented on a man page (manual page) here is a short HOW TO to get you started: http://www.tldp.org/HOWTO/Man-Page/index.html
Yes, but ...
Man pages are certainly the usual way to provide reference-type
information, and they're the definitive source for many Unix
environments--that is, you cannot ignore them--but they're
not really the full story. See below...
smithelizabeth -at- hotmail -dot- com wrote:
I am new to unix and have been asked to document custom unix utilities for
our system administrators. Does anyone have any info for documenting
custom unix utilities or where I could go for ideas or a place to start?
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?)
Probably not. The most effective documentation I've used (and the
best-received documentation I've created) has been task-oriented,
rather than focused on the tools used. That is, if you can envision
your audience sitting at the terminal and saying "Wow, I'd really
like to use the foo command today", then feel free to tell
them how to use the foo command. On the other hand, if they're
more likely to want to know how to do something--like add a user
or configure a whatzis--then offer "How to add a user" or "How to
Configure a whatzis" as tasks.
There are five separate custom unix utilties, which can be called from
either the graphical user interface or the command line.
Aha--a GUI is another gotcha for man pages--you'll want to have
an alternative delivery medium for the docs, or at least the ones
covering the GUI.
- A tool used to create, update, and maintain information common to all
telephone numbers in the customer database.
- A tool used to create and modify uid files and update param files.
- A tool used to change, modify, or print feature information on customer
stations.
- A tool used to create, modify, or verify a customer's extension ranges.
- A tool used to create, update, and maintain information common to all
customers in the office. It specifies the parameters of an office.
Looks like you just defined the tasks needed. Ask yourself if the
users will care more about the tool or getting the task done, then
structure the docs around the necessary tasks, with man pages to
supplement the task-oriented docs.
Eric
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ROBOHELP FOR FRAMEMAKER TRIAL NOW AVAILABLE!
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.
References:
RE: Documenting unix utilites: From: Gilger.John
Previous by Author:
Re: XML-based Help Authoring tools for customized help
Next by Author:
Re: Word Count for 100 Files?
Previous by Thread:
RE: Documenting unix utilites
Next by Thread:
Re: Documenting unix utilites
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads