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.
My earlier response was rejected because I included a screenshot -- anyway my two cents were that, for our script examples we use coloring for different sections (much like an HTML code editor would do) and then we chose to place a highlight (background color) over the area the user is supposed to type into or change. As far as our support-facing CHM that goes along with one of our products, we break it up into topics about what the code section does ("Configuring X Y Z") and then discuss where the config file is, andÂshow the code sample (in our case we can screenshot, but I do have my TWs change the color of hte highlight sometimes), talk about the default setting, be sure to make it extra clear which part to change (as in, "put the desiredÂvariable between the quotes") and so on.
As far as long code examples, it is a bit old school and it's very tech-writer minded to simply talk about it from an aesthetic point of view and say long code samples are a thing of the past. It heavily depends on what you're writing about. If I'm looking at documentation for an API, then it's ALL CODE! :)ÂÂCode monkeys LOVE this stuff and want to see the nuts and bolts. The goal is to not have an admin have ANY questions after seeing documentation about whatever it is you're documenting.ÂIf you're producing something that has a lot of long-chunks of code in it then keep them in the text in normal flow, but if there's only a few long examples and most are short, put the long parts in an appendix and reference the appendix in the text if you canÂ(someone else said this too I think).
And don't edit code for the most part -- you can, however, edit the comments in the code (assuming you can recognize comments). If you can break up code to talk about which sections do what, they do that when you can. 5-10 lines of code at once is optimal for smaller chunks, but if your project needs the longer lines, (I've seen pages and pages of code before it goes to regular text) then go with it. Don't get hung up about how much space it's taking up if that's what the project needs.
Hannah L. Drake
Lead Technical Writer
Formulatrix, Inc.
781-788-0228 x137 (office)
617-610-6456 (cell)
hannah.drake.formulatrix (skype)
On 11/25/2013 4:32:26 PM, McLauchlan, Kevin <kevin -dot- mclauchlan -at- safenet-inc -dot- com> wrote:
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
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
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 Submit" (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.
