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:Lynne Wright <Lynne -dot- Wright -at- tiburoninc -dot- com> To:"Elissa K. Miller" <emiller -at- doubleknot -dot- com>, techwrl <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Mon, 25 Nov 2013 18:17:51 +0000
Showing an example of output for each command seems like a big waste of space. It's a pretty old-school mindset that insists on showing e-v-e-r-y-thing, but you'll need some kind of evidence to convince your client that people generally don't like to wade through pages and pages of illustrations of stuff that they're going to see on-screen anyway. If you can find some on-line resources about principles of usability that support your case, you may be able to bring them around. If the client is still sending out hard copies to customers, you can make the case that reducing the page count will save them printing and shipping costs.
Font formatting in examples... could you just show the example, then add a table that lists commands in one column, and the value that they need to enter in another column?
Page numbering issue: Given that I only provide our docs as pdf, I've been thinking that I should rework the page numbering in my Framemaker source docs to avoid that numbering mismatch in the pdf (i.e. the title page would be Page 1). If there's a workaround in Acrobat, I'd like to hear about it too.
-----Original Message-----
From: techwr-l-bounces+lynne -dot- wright=tiburoninc -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lynne -dot- wright=tiburoninc -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Elissa K. Miller
Sent: Monday, November 25, 2013 11:53 AM
To: techwrl
Subject: Standards for command-line documentation + dumb Acrobat X user question
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.
