Subject: Re: Andy's review of draft-ietf-snmpconf-pm-09.txt

From: "Joel M. Halpern" <[email-masked]>
Date: Sat, 26 Jan 2002 15:31:57 -0500

[I will re-read Andy's comments, but I noted a couple of patterns and I 
think that addressing the reasons for the patterns may help.]

1) A number of the comments about document structure, insufficient 
information, and other "errors" appear to arise from a single cause.  In 
our efforts not to mandate a single implementation strategy, we seem to 
have forgotten to give the reader enough information to actually do the 
implementation.  I overlooked this (and presumably so did the authors) 
because by this time in the process I have lots of assumptions in my 
head.  However, given how frustrating it is when I have to work with other 
under-specified RFCs, I think that we need to look at putting a lot more 
descriptions of possible implementations into the document.

2) Andy comments repeatedly about strings appearing in places where they 
"are not allowed".  It appears that Andy missed (and therefore we need to 
emphasis better) the fact that these strings are supposed to be processed 
on the front end.  The fact that we are not mandating a front end, but are 
describing all our examples as if there is a smart front end does produce a 
tension (rather like the on in (1) above) that should be addressed.  I 
actually muchly prefer the use of the text strings, as if the examples used 
explicit numeric OIDs I would have no idea what the examples were doing.

Yours,
Joel M. Halpern

---

From: Andy Bierman <[email-masked]>
Date: Sat, 26 Jan 2002 13:10:33 -0800

At 12:31 PM 1/26/2002, Joel M. Halpern wrote:
>[I will re-read Andy's comments, but I noted a couple of patterns and I think that addressing the reasons for the patterns may help.]
>
>1) A number of the comments about document structure, insufficient information, and other "errors" appear to arise from a single cause.  In our efforts not to mandate a single implementation strategy, we seem to have forgotten to give the reader enough information to actually do the implementation.  I overlooked this (and presumably so did the authors) because by this time in the process I have lots of assumptions in my head.  However, given how frustrating it is when I have to work with other under-specified RFCs, I think that we need to look at putting a lot more descriptions of possible implementations into the document.

It's not really under-specified, but rather just not well organized.
The big areas for improvement:
  - explain the whole before diving into the details of the parts
  - collect related information into one place 
  - remove all forward references to concepts, MIB objects, and terms
  - make examples consistent and correct, and use lots of them
  - attempt the clarify the runtime behavior and document one
    suggested implementation strategy of the runtime environment

>2) Andy comments repeatedly about strings appearing in places where they "are not allowed".  It appears that Andy missed (and therefore we need to emphasis better) the fact that these strings are supposed to be processed on the front end.  The fact that we are not mandating a front end, but are describing all our examples as if there is a smart front end does produce a tension (rather like the on in (1) above) that should be addressed.  I actually muchly prefer the use of the text strings, as if the examples used explicit numeric OIDs I would have no idea what the examples were doing.

IMO, the WG is making a flawed assumption about scripting, by
requiring a front end to translate some parts of the source code 
before loading the pmPolicyCodeTable. Humans should be able to 
generate 100% of the source code without additional tools.
(That's why I put an OID Alias table in the SEE MIB.)

The examples should show the real ASCII-dotted OID and the string
version in a comment.  It is very confusing to see all those
verbose disclaimers about how the code really doesn't look like
this -- it's human nature to assume the authors would only include
valid examples of the programming language, and base their own
code on those examples.  

It would be extremely challenging for a non SNMPCONF WG member to 
fully implement the PM MIB just by reading this document, let alone 
getting two of them to create inter-operating implementations.

>Joel M. Halpern

Andy