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.
Subject:Procmail, and an article critique From:SIANNON -at- VISUS -dot- JNJ -dot- com To:"TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com> Date:Wed, 12 Dec 2001 8:42:4
OK, a while back someone asked about spam-protection, some other folks
were discussing how the implementation of Linux platforms affected their
tool choice, etc. At that time, I wanted to compose and post a brief
procedure on using procmail to filter out the junk, but I was unable to
find the old posting I had on it from a friend of mine.
Then, this morning I ran across a link to this article on setting up
procmail in a security newsletter:
It is my understanding that procmail works on Linux and Unix
platforms, and requires one part to be set up on the server by the admin.,
and another to be set up by the user (to determine who gets weeded out, and
where to). What I had seen before was simple instruction on setting up the
filter file to redirect spam to \dev\null or abuse@ locations. I also heard
of such filters being used to block out or misdirect doubleclick ads and
cookies during web-browsing, to prevent them from hanging your page
download, or successfully snooping on your usage (I'm fuzzier on this
part). All in all a very nifty tool to share.
Now, the article seems to be instructions on configuring the server
side, with notes on the client side "recipes". At first I was extremely
happy to find it. Then I tried to read it, and kept hearing the first
commandment of tech writing gibbering in the back of my head ("Know thy
It seemed to me to be an excellent example of a procedure written with
too many assumptions about the audience. Sure, given where the newsletter
is posted, maybe she really did write it for a narrow band of audience
already familiar with setting things up on a *nix system, who all use the
same terminology and definitions for everything. However, the document type
suggests it is supposed to be geared toward instructing newbies. I have
very little *nix background right now (just enough to shoot myself in the
foot and know what I *could* do if I dedicated a little time to it), so I
assume many of the things that confused me might also confuse a newbie user
just trying to learn the tech. Procedures like these are very likely to be
used/referenced by new users not already indoctrinated in the vocabulary.
Related technical concept for discussion:
I believe writing for web publication has brought the analytical depth
of technical writing into higher awareness. Print materials have had a more
limited readership, so control of the target audience was easier to
maintain, and some assumptions about terminology and previous knowledge
could be made. Now, anything you write for the web may be read by nigh on
anyone. All of a sudden, your audience has expanded outside the original
I used google to look up some articles on Use Cases after an earlier
discussion, and was amazed by the theoretical knowledge each one assumed a
reader would already have become acquainted with. One or two came across as
Swahili to me, and I am usually quick on the uptake (I've read complex
biotechnology research for amusement, and had less problem comprehending
what is being described than one of the articles).
Now, I'd had Use Cases described to me before looking at any of those
sites, and not a single one of the sites I visited (I gave up after the
fifth page of results) described them the same way they had been described
to me, originally. The original description was simple: a use case is a
scenario representing a use of the product to accomplish a specific task;
permutations of each scenario are used to establish possible alternate
courses of action, from which failure testing and the possible
error-trapping/alarms needed can be determined, and test cases can be
constructed. Scope and level of detail may vary.
After reading the sites that came up in my google search, I understand
why my team never bothered to develop any. If they were developed according
to those instructions, the project would never have gotten off the ground.
Now, however, I'm trying to go back and build a scenario tree for
diagnostic purposes, and it's difficult to determine the most productive,
least time-consuming way to do so (our system automates a manual process
that loops in several places, so the variations are geometric). Part of me
is frustrated, because I feel I am cleaning up a mess caused by the poor
communication of others. Part of me believes that perception is unjust if
the original authors were assuming a different audience for their work;
they would not be at fault for the perceptions of the developers who've
stumbled across it.
Request for your opinions:
Given the nature of the web, what responsibility do you give the
author for identifying the scope and audience of published/posted content?
How do search engines throw a wrench into audience analysis?
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr
Your monthly sponsorship message here reaches more than
5000 technical writers, providing 2,500,000+ monthly impressions.
Contact Eric (ejray -at- raycomm -dot- com) for details and availability.
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit http://www.raycomm.com/techwhirl/ for more resources and info.