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.
In a previous incarnations, I've documented software that either
implemented or conformed to a number standards, including the dreaded
ASN.1 as well as SNMP, GR/TR-303, ISO, et cetera ad nauseum - obviously in
the telecom industry. As an aside, I actually miss digging through the
standards (and the code) to figure out what the software was supposed to
do (or actually did).
One of the biggest problems the devel'ers (and I) had was dealing with
ambiguity in the standards. Some of the ambiguities may have been
intentional, as when members of the standards committee cannot agree on an
issue and leave it up to implementers/standards users to make a decision,
and other ambiguities were, I suppose, due to poor writing (no offense
intended - ambiguity can sneak its way into almost anything). The
devel'ers handled both by drawing on what they knew of how the standard
was developed (some of the participated on the dev commitees and could
explain what the heck they intended by certain phrases, sections, etc.)
and by agreeing on how to interpret the ambiguous pieces. Based on this, I
would suggest two things:
1. Include information about the intended ambiguities: what the opposing
positions were/are and glimpses into the reasoning behind these positions.
I vaguely recall it being difficult to distinguish between intentional and
accidental ambiguities - doing this would at least identify the
intentional ones and take the pressure off the non-writers charged with
writing the standards to produce well crafted stuff. (I shudder to think
that I am somehow suggesting that these are not and may not need to be
well written. Maybe I'm not ... anyway. Onward.)
2. I don't know what kind of review process goes on, but I'd suggest that
someone who isn't familiar with the particular standard but is technically
adept be included in that process. Assuming there are non-native,
non-fluent English speakers and writers responsible for these puppies,
they should get - at the very least - a native or near-fluent English
speaker to review the standard before it heads out the door.
Now that I think about it, I also remember lusting after an index,
especially with the ITU-T standards, because of the number of documents
and the tendency of certain items, like ASN.1, to be covered in a number
of different places.
Hope this helps.
Mandy Kinne
___________________________________
Mandy Kinne
Team Lead, Documentation and Process
NeuStar, Inc. http://www.neustar.com
___________________________________
"verba volant, scripta manent
(what is said vanishes; what is written remains)"
courtesy of David Coward's notes in the Oxford World's Classics edition of
Alexanre Duma "La Reine Margot"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com
Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr
---
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.
