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:"rebecca officer" <rebecca -dot- officer -at- alliedtelesis -dot- co -dot- nz> To:<emiller -at- doubleknot -dot- com>,"techwrl" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 26 Nov 2013 17:43:43 +1300
We create a detailed command reference for embedded hardware, so we have at least half a page per command, and often multiple pages.
For "show' commands, we try to put an example of the output, plus a table that explains what each item in the output means. Some of these are more obvious than others! If the output's repetitive, we're likely to only show it once. We use 3 vertical dots to show that stuff's missing.
We do configuration examples for every command. We don't include screen responses in those, to reduce the clutter. So we give a lead-in sentence, then just list the command prompt and the command itself. If we were listing screen responses, I'd definitely use bold or colour to show what people enter!
We also list the full syntax of each command, like this:
virtual-link <router-id> [hello-interval <1-65535>]
<> means it's a variable or user-chosen number. [] means it's optional. We use Courier font and we also put the variables in italics, to make it clearer that they're variables.
In longer examples, we sometimes use bold to highlight stuff.
The thing that matters most is syntax consistency and getting your examples tested. Make sure they work.
I can point you to one of our docs, if that'd help.
Cheers
Rebecca
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.
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
NOTICE: This message contains privileged and confidential
information intended only for the use of the addressee
named above. If you are not the intended recipient of
this message you are hereby notified that you must not
disseminate, copy or take any action in reliance on it.
If you have received this message in error please
notify Allied Telesis Labs Ltd immediately.
Any views expressed in this message are those of the
individual sender, except where the sender has the
authority to issue and specifically states them to
be the views of Allied Telesis Labs.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
