Standards for command-line documentation + dumb Acrobat X user question

Subject: Standards for command-line documentation + dumb Acrobat X user question
From: "Elissa K. Miller" <emiller -at- doubleknot -dot- com>
To: "techwrl" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 25 Nov 2013 08:52:44 -0800

Hi, all:

For nearly 20 years, I've created documentation and training materials about
all kinds of GUIs. Now, I'm documenting a command-line interface for
managing a hardware product. I'm encountering some issues that have
certainly been addressed by professionals accustomed to working with CLIs.

. Examples. For each command, the client wants to show sample
output. In some cases, this is dozens of lines of text. I find it hard to
believe that this is useful. My argument is pretty much the same as the one
against page after page of screen shots. I can see the point of a lengthy
code sample-you can learn something from all of it-but a screen dump of what
happens when you type a specific commands seems useless to me. I'm sure this
is a battle that has already been fought and there's an accepted industry
standard for it that technical writers can live with. What's the general
approach for this?

. Formatting of examples. All the examples are in a monospace font,
similar to the CLI. Some of their examples involve issuing a series of
commands, so the sample contains the command prompt and the text they enter,
followed by several lines of text, followed by another command prompt and
text that they enter, etc. To make it easier for a reader to find the
commands that they actually enter, as opposed their eyes glazing over at the
voluminous output, I applied bold to the lines in the sample that were
user-entered (I didn't change the font). A reviewer flipped out and said I
shouldn't do that. But, in the same way that I'd write, "Do whatever and
click <b>Submit</b>" (with Submit bold and a different font), it made sense
to me to highlight what the user actually has to enter. Like the previous
query, I'm sure the battle of whether to make it easy to find the user
commands in a giant pile of monospace output has already been fought. Who

And, the last problem is just dumb Acrobat X user stuff. I had a reviewer
complain that the page numbering in the PDF did not match page numbers in
the PDF. This is true, because the title page and two-page TOC weren't part
of the main pagination-the real document starts on what Acrobat thinks is
page 4, but is marked as page 1. If you print the manual, it makes perfect
sense, because the only page numbers you see are the one on the pages. I
wasn't envisioning anyone using the TOC or Word-based page numbers in the
manual-the bookmarks are based on headings 1-3, so within the PDF,
everything in the TOC is more easily and logically accessed from the
Bookmarks pane, which opens automatically. Does anyone have either a
throwdown answer for why I can politely ignore his suggestion, or the name
of the Acrobat X command that would somehow make the fourth page of the PDF
behave like page 1, and if they type 1 into the Reader field, it would take
them to what's really page 4? I think this must be RTFM, and maybe I've
completely lost my mojo at structuring a query, but I can't get a decent
answer out of Adobe's online help or the Internet. My feelings won't be hurt
if you roll your eyes and send me the output from Let Me Google That For
You-I just need to figure out if it can be addressed, and if so, how. (And,
if not, how to respond to this guy.)

I know that these questions are very, very basic stuff. I'm a decent
instructional designer and tolerable technical writer (especially compared
to the engineer-driven docs that I started with) but I don't know the
standards for CLI docs and Acrobat X is just eating my lunch.

Thank you for referring me to existing information about the structure of a
wheel so that I don't have to invent my own from scratch, because my wheel
would take too long to build and probably wouldn't roll very well because a)
I designed it myself and b) I would have been forced to accommodate the
not-always-helpful modification requirements of my content providers.

And that's my tortured metaphor for the day.


Elissa Miller

New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more:


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


Previous by Author: Re: Printing a booklet
Next by Author: So now we are content engineers?
Previous by Thread: RE: TechWhirl: Technical Communication Recap for November 22, 2013
Next by Thread: Re: Standards for command-line documentation + dumb Acrobat X user question

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

Sponsored Ads

Sponsored Ads