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

[Kathleen MacDowell <kathleen -dot- eamd -at- gmail -dot- com>]

Also, if there are a huge number of examples, perhaps you could put the
least important of them into an Appendix? For example, with the CLI,  you
provide 4, then note, See Appendix X, ref X, for more examples.

Kathleen


On Mon, Nov 25, 2013 at 10: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 kathleen -dot- eamd -at- gmail -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
>



-- 
Kathleen MacDowell
kathleen -dot- eamd -at- gmail -dot- com


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