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.
> Naturally, I have a standard format (color, size, font, and underline)
> for hyperlink text.
>
> Mostly, that works, and nobody complains.
>
> However, many command-line interface commands have sub-commands and
> options that get their own pages.
>
> So, an intro page for a major command will have just a list with the
> subcommands under headings,
> mimicking the look of the command-line summary syntax, like:
>
> widget - manage widgets in the system
> The following sub-commands are available:
>
> Name (short) Description
> ===== ====== ===========
> add a Add a new widget
> delete de Delete a named widget
> clear c Delete all widgets
> enable e Enable a widget by name
> disable di Disable a widget by name
> show s Show info about a named widget
> list l List all widgets
>
>
> Naturally, it would be nice if each sub-command's Name were to be a
> link to the page that describes that command.
>
> How important would it be to you (and why):
>
>
> - that the link words keep the same appearance as links
> anywhere in the WebHelp, so it's obvious they are links
>
> - that the link words be modified to blend in with the CLI
> look-and-feel, and users will just know that they are links?
There are two goals that appear to conflict: (1) let users know the sub-commands are links and (2) maintain the CLI look and feel. But both goals could be satisfied by changing the command intro as follows:
widget - manage widgets in the system
The following sub-commands are available (click a sub-command for more information):
Would a compromise like that satisfy the concerns of both camps?
Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-903-6372
------
