Re: I'm struggling with 2219 language again

[Hector Santos <[e-mail]>]

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