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.
> "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
