After very carefully reading Ron Bergman's message, I find myself
agreeing with Ron pretty much up and down the line.
Quick comments:
- I like Ron's proposed wording in every single case; I find
the Job MIB tends to read more like a legal contract than a
useful specification. Sorry, but the comments about "active voice"
are just not all that useful, given that Ron's sentence is far
cleaner and completely unambiguous. (I mean, who cares that you
call out the agent versus something else?? If a value is supposed
to be 0, then IT IS ZERO, regardless of who sets it or receives it.)
- Ron's insistence on moving certain examples to the "mapping section"
of the document is also right on track. I find the PCL "example" only
marginally useful and not worth the many words used to describe it.
If words exist in the main body of the spec, then the reader will be
compelled to carefully read and evaluate them; if those words exist
only to "clarify" a rather nitty point, then the reader grows quite
weary and distracted. This is Not Good. Move all such stuff to the
mapping section.
- I found the interchange on "human perceptibility" to be totally bizarre.
(At first I thought it was some kind of joke.) Get rid of it!
This is the Job MIB for heaven's sake, and not some treatise on a cure
for cancer, or a discourse on human strife and suffering. Keep it SIMPLE.
- A FAQ is always, ALWAYS an excellent addition to any specification,
and we should try to move things to the FAQ whenever possible, IMHO.
I like Ron's suggestions in this area, and strongly suggest adopting
his suggestions.
Ron had asked for opinions. ;-)
I must say, however, to the JMP group at large:
I am totally appalled by this situation. The MIB Editor is supposed to
maintain the document according to group consensus, and such consensus
is managed by the project chairperson, based on open dialog on the JMP
mailing list. I thought everyone was aware of these "rules" of conduct
within the PWG (as "borrowed" from the essential rules of IETF working
groups).
The fact that the JMP MIB Editor made a number of unilateral decisions
on the document--and then posted the document without first responding
to Ron's editorial proposals--is TOTALLY unacceptable. The fact that
Ron Bergman is the JMP Chairperson makes the situation even more
unacceptable, especially since Ron has done such a fine job in
eagle-eyeing the document all along.
I trust this kind of situation does not happen in the future, because
if it does, we'd be wise to appoint a new MIB Editor. Yes, I realize
these are harsh words, but this is a completely UNACCEPTABLE situation
that should never have happened in the first place.
...jay