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 question for the list was anticipated, maybe even precipitated, by the
recent 'fake names' thread. I'm amazed that the rhetorical use of names in
examples can cause problems, and I've got a more extreme example of how
this "referent problem" forces us to go to some lengths to avoid possible
inconveniences, legal problems, etc..
Anyway, this is a documentation issue, so I hope someone will weigh in with
useful idea or solution.
The problem: I used a book from one of the big computer presses to get
some ideas on how to write about command line commands on routers. The
examples they used were entirely made up using non-internet-routable
addresses, even where the command syntax called for an internet-routable IP
address. These dessicated examples are bad news for me, when I'm learning
about this stuff!
The risk of publishing a real routable IP address must be too great,
(someone might actually ping it?) so we get examples that don't look right.
This is slightly different problem from the 'fake names' problem, where a
solution needs the form of a name to work for the reader; with IP addresses
it is the actual numbers that look right or wrong.
To me, these examples look egregiously wrong and misleading. It's like
kneading a cobblestone to learn how to make bread, you loose the hands-on
information. I wonder why real examples of network configuration tasks are
not valued by the publishers/editors/writers/students? Is it because these
things are usually taught in a classroom where embellishment is possible?
For my money, the market for self-paced courseware books and certification
is robust and publishers should be able to have a few IP addresses set
aside for examples. A few blocks on a few different networks, a few blocks
on different subnets and fairly lifelike examples would be easy to create.
Clearly, non-routable addresses in routable address examples is something
that professionals can learn to live with (the network engineers I talk to
fairly sneer at this idea), but as an exercise in problem solving and a
demonstration of professional demeanor, shouldn't Internic, or a standards
body, or STC, or some big organization with lots of money/clout/ip
addresses set up an address reservation for us poor example-starved users
and writers of internet hardware/software docs?
Is there a better solution that I'm overlooking?
Edward Bedinger
Edword Technical Communications Co.
Seattle, WA
---------------------------------------------------------------------------
If this were merely my opinion, I'd probably keep it to myself.
My employer is not responsible for my expressions.
