RE: Command Line Interfaces

Subject: RE: Command Line Interfaces
From: Janet Valade <janetv -at- systech -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 30 May 2000 13:04:26 -0700


> "Perry Moore" <perrya -at- jps -dot- net> wrote:
>
> >I recently saw an ad for a TW where it stated that having experience with
> >Command Line Interfaces was a plus. What are these? What does one have to
> >know as far as documentation goes? Why would this experience be a plus?
> Does
> >anyone have a sample?
>
TW who are used to writing only for Windows apps tend to think in
terms of screen shots and describing what the user sees and pointing to
things. You assume the user is looking at a bunch of menus and other cues. A
user using a command line interface is looking at nothing. There are no cues
what to do next. The user is pretty much dependent on the doc (there may be
online help or may not, but the user first needs to be told how to access
it). Your docs have to be really well organized and have a good index.
Reference material is essential that describes all the available commands
and their options. Often commands are not obvious. E.g. in UNIX, cp to copy
and mv to rename.

You can look at my manuals that are on-line to see a manual
documenting a command line interface. Keep in mind that the users are system
administrators, so I assume that they know their way around UNIX well.
http://www.systech.com/support/rcs4kagg/rcs4kdoc.html.

Some burning issues are:
1. how to distinguish the commands from the commentary and
descriptions
2. whether to include instructions to press enter at the end of
every command or to assume that one overall instruction to press enter at
the end of every command is sufficient.
3. when a command is too long to fit in a single line of the manual,
how to indicate to the user that the next line is a continuation of the
previous line and you should not press enter at the end of the first line
4. how to convey the difference between text that should be typed
exactly as shown or text that is meant to be replaced by user-specific
variables.
5. how to convey the difference between arguments that are required
and arguments that are optional

Janet

Janet Valade
Technical Writer
Systech Corporation, San Diego, CA
mailto:janetv -at- systech -dot- com









Previous by Author: Web site questions
Next by Author: Re: Good graphics & clip art
Previous by Thread: Command Line Interfaces
Next by Thread: Re: Command Line Interfaces


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


Sponsored Ads