Re: Making better standards

Subject: Re: Making better standards
From: Mandy_Kinne <emeeekay -at- enteract -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 12 Apr 2002 12:07:09 -0500 (CDT)


Jonathan,

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.



References:
Making better standards: From: Jonathan West

Previous by Author: Online graduate education
Next by Author: Re: Techwriter's toolkits and directions for tomorrow (long and deep response) (fwd)
Previous by Thread: Re: Making better standards
Next by Thread: RE: Poll suggestion: Lurkers


What this post helpful? Share it with friends and colleagues:


Sponsored Ads