Scott Brim wrote:
It's a communication problem. If you want your audience to understand
exactly what you're saying, and implement along very specific lines, you
need to tell them in a way they understand.
+1
Personally I prefer a quieter approach, but I've been told that
these days one MUST use MUST or implementors just won't get it.
"Huh, that's a requirement? But you didn't say MUST."
I believe in the technical writing style of "Being specific is Terrific!"
I suggest
turning this thread into a survey, and
finding out how people who actually write code look for in order to know
what's required.
+1
We have implemented numerous protocols since the 80s. I have a
specific method of approaching a new protocol implementation which
allows for fastest implementation, testing proof of concept and above
all minimum cost. Why bother with the costly complexities of
implementing SHOULDs and MAYs, if the minimum is not something you
want in the end anyway?
A good data point is that for IP/Legal reasons, we do not use other
people's code if we can help it and in the early days, open source was
not as wide spread or even acceptable at the corporate level. In other
words, it was all done in-house, purchased or nothing. I also believe
using other people's code has a high cost as well since you don't have
an in-house expert understanding the inner workings of the externally
developed software.
o Step 1 for Protocol Implementation:
Look for all the MUST protocol features. This includes the explicit
ones and watchful of semantics where its obviously required or things
will break, perhaps it fell thru the crack.
An important consideration for a MUST is that operators are not given
the opportunity to disable these protocol required features. So from a
coding standpoint, this is one area you don't have to worry about
designing configuration tools, the UI, nor including operation
guidelines and documentation for these inherent protocol required
features.
This is the minimum coding framework to allow for all inteop testing
with other software and systems.
The better RFC spec is the one that has documented a checklist, a
minimum requirement summary table, etc. Good example is RFC 1113 for
the various internet hosting protocols. I considered RFC 1123 the "bible!"
Technical writing tip: Please stay away from verbosity especially of
subjective concepts and please stop writing as if everyone is stupid.
I always viewed the IETF RFC format as a blend of two steps
of the SE process - functional and technical specifications.
Functional specs tell us what we want and technical specs
tell us how we do it. So unless a specific functional requirements
RFC was written, maybe some verbosity is needed but it should
be minimized.
Generally, depending on the protocol, we can release code just on
using MUST requirements - the bottom line framework for client/server
communications. Only when this is completely successfully, can your
implementation consider moving on at extending the protocol
implementation with additional SHOULD, MAY features and its optional
complexities.
o Step 2
Look for the SHOULDs. This is the candies of the protocol. If the
SHOULD is really simple to implement, it can be lumped in with step 1.
I know many believe a SHOULD are really a MUST as an alternative
method perhaps - different version of MUST to be done nonetheless.
However, I believe these folks play down an important consideration
for implementing SHOULD based protocol features:
Developers need to offer these as options to deployment operators.
In other words, if the operator can not turn it off then a SHOULD was
incorrectly used for a MUST which is required with no operator option
to disable.
o Step 3
Look for the MAYs. Very similar to SHOULD, a good way to consider a
SHOULD is as a default enabled (ON out of the box) option and a MAY as
a default disabled (OFF out of the box) option.
Summary:
MUST - required, no operator option to disabled. Of course,
its possible to have a hidden, undocumented switch
for questionable stuff.
SHOULD - good idea, recommended. if implemented, enabled it
out of the box.
MAY - similar to SHOULD, does not have to be enabled out
of box.
In both cases for SHOULD and MAY, the operator can turn these protocol
features off/on. For a MUST, the operator can not turn the MUST
feature. These SHOULD/MAY features are documented for operators and
support.
One last thing, I believe in a concept I call CoComp - Cooperative
Competition, where all competitive implementators, including the
protocol technology leader all share a common framework for a minimum
protocol generic to all parties and the internet community. It is
least required to solve the problem or provide a communication avenue.
All else, the SHOULDs, the MAYs, is added value for competing
implementators. It generally is what differentiate the various
implementators software.
I personally believe it is doable to write a new RFC that describe a
guideline for protocol development that will minimize conflicts at
many levels. Of course, a major part of that is good technical
writing skills in principle and the ability to extract and describe
what the protocol framework is, which brings it all back to the
original issue using the proper communications verbiage to describe a
protocol.
--
HLS