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