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.
On Mon, 1 Dec 2003 16:47:05 -0700, smithelizabeth -at- hotmail -dot- com said:
>
> I am a bit lost, and would like some advice concerning my next project.
>
> 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?)
Hi Beth,
As others have explained, most of the UNIX documentation is in the form
of man pages. Apart from man pages, there are some key documents that are
delivered in the printed format. Typically, the system administrators'
tasks are documented in documents such as the installation guide,
administrator's guide, troubleshooting guide, etc. that are bundled with
the product. If you limit your documentation to man pages, your users
will find it difficult to locate information and understand the processes
to follow to perform the various tasks, especially if the tasks are going
to be performed at the installation/configuration stages.
Analyze the tasks in detail and create usable documentation in one or
more formats, depending on your audience profile and nature of tasks. If
you are creating man pages, try to explain the commands using enough
examples. For GUI-based applications, it would be better if you have an
online help integrated with the product. The online help should be
task-based and easily accessible. You can provide ample information about
all the tasks along with examples to make your users understand the
concepts and procedures easily.
Most of the companies develop online help using their proprietary
formats/tools. I am not aware of any tool that is available in the market
for developing online help for UNIX-based applications. AFAIK, HTML-based
online help can be integrated with such applications, but you have to be
sure that your help files will work on browsers that your flavor of UNIX
supports. Try to find out from your developers whether there are any
tools or formats available for creating online documentation for your
version of UNIX or they can develop one for creating documentation for
all products across the organization. :) Some of the popular man page
formats are nroff and troff. These formats contain a set of macros that
will take care of the formatting of man pages. The following links will
be of help in learning nroff/troff formats:
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.
