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

Subject: Re: Standards for command-line documentation + dumb Acrobat X user question
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: techwrl <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 25 Nov 2013 09:57:54 -0800

I follow the Microsoft Manual of Style 4 guidelines for command
syntax. In a context where italic is not available to indicate user
input, I use <angle brackets>.

When possible, use a monospace font that clearly distinguishes between
l, I, and 1, and between O and 0.

It's not standard to include sample output if it's voluminous.

Making page numbers show up in Acrobat Reader so they match a printed
book (Cover, i, ii, 1, 2) depends on the authoring application.
InDesign can do that. I just number from 1 and suppress the page
number on the cover.

On Mon, Nov 25, 2013 at 8:52 AM, Elissa K. Miller
<emiller -at- doubleknot -dot- com> wrote:
> 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
> won?
>
>
>
> 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.
>
>
>
> Best,
>
> Elissa Miller
>
>
>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
>
> Learn more: http://bit.ly/ZeOZeQ
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as robert -at- lauriston -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
> http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


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

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
Standards for command-line documentation + dumb Acrobat X user question: From: Elissa K. Miller

Previous by Author: Re: Printing a booklet
Next by Author: Re: need a word for "ranging"
Previous by Thread: Standards for command-line documentation + dumb Acrobat X user question
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