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:"McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com> To:Kathleen MacDowell <kathleen -dot- eamd -at- gmail -dot- com>, "Elissa K. Miller" <emiller -at- doubleknot -dot- com> Date:Mon, 25 Nov 2013 16:32:13 -0500
Good points.
My take on how many or how thoroughly to provide examples is:
- if a command is in the product, somebody is going to use it
- if I want to use a command, I want it documented, including an illustrative example... in fact, I wouldn't mind seeing examples of failure scenarios, like what messages to expect if you forget to log in before issuing the command, or how the output might differ for different levels of user, where that's relevant
- if a command is trivial to document, then the example should be quick and easy to provide, no?
Except in situations where I just can't get the right equipment (or enough of it), I make my own examples.
In the case of a long example sequence of many commands and their output, I might trim the middle out of overly-large blobs of output and replace with a nice " [...snip...] ". In that case, I precede the example with a note like "Parts of this example are trimmed for space reasons '[...snip...]'."
In such long examples, I shamelessly use bolding and color to make the "what you type" bits stand out.
If I include a "show" command before an action command, and then another "show" command following it, to illustrate the change, either I'll leave the entire output as-is, or I'll snip but leave enough for the reader to orient herself.
If a changed portion is a few words or a string of numbers, I'll change its color (but otherwise leave it in the Courier New that my <pre> tag applies).
Several words, or a bunch of numbers in a different color should catch most visual scans.
If the changed portion is just a character or three, and could get lost on a page of text, even with the color difference, I might stick " <<====" to the right, to catch the scanning eye of the reader.
I avoid getting fancy. There's a non-zero chance that I'll have to re-import the example within the next release or three.
-k
PS: The "this has changed" color was a shade of red for years, but recently became a shade of orange that is one of our corporate colors. I've verified that color-blind males see it as sufficiently different from the surrounding black text. No females at this location admit to being color blind.
-----Original Message-----
From: Kathleen MacDowell
Sent: November-25-13 1:08 PM
To: Elissa K. Miller
Cc: techwrl
Subject: Re: Standards for command-line documentation + dumb Acrobat X user question
Elissa, I haven't worked with Acrobat for a while, but I'm pretty sure that you have an option to start page numbering @ n.
Maybe worth a shot if you haven't already done that.
In general, I try to pick my hills, because even those don't always work out. But I agree with you about the formatting (also see Robert's MMOS refs). Number of examples--I'd probably leave that up to the mgr, so long as it could be formatted so the reader could understand. On the other hand, if you can get them into an agreeable frame of mind, you might suggest that they focus on important or distinctive ones rather than sheer number.
Here's one very encouraging thing about the people you're working with--they want to document their product (or whatever you're working on :-), and it sounds like they want to do a thorough job, which is super.
Best of luck
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?
[... snip ...]
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
