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.
I'm producing WebHelp, where a large component of the documented system is operated by command-line.
I have "standard" fonts and colors that I use throughout the Help in loose compliance with our corporate branding.
I say "loose" because, as you know, browsers (and their users) are free to substitute fonts with alacrity and abandon.
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?
FWIW, I'm in the former camp.
Some of my documentation reviewers are in the same camp.
Others of my documentation reviewers are in the latter camp.
None of the people with strong opinions are my boss/person who signs my evaluations...
-k
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
