Subject: [eman] Ira's comments on draft-ietf-eman-energy-monitoring-mib-08

From: Ira McDonald <[email-masked]>
Date: Fri, 27 Dec 2013 16:47:59 -0500

Hi Benoit et al,                           Friday (27 December 2013)

Here are my comments on draft-ietf-eman-energy-monitoring-mib-08:

(0) Global (missing series comma)
- please always use an explicit comma between the penultimate and
  ultimate words/phrases of a list - this can avoid ambiguity and
  is always clearer writing - the explicit series comma is omitted
  throughout the current draft

(0) Global (missing trailing comma)
- please always wrap "i.e." and "e.g." with leading and trailing
  commas - the trailing comma is incorrectly omitted throughout
  the current draft

(0) Global (misuse of explicit numeric values of enumerations)
- please remove all explicit numeric values of enumerations in
  preface and body text of MIB modules - these values are frequently
  wrong and they create hard-to-find documentation errors

(1) Page 6 (readability)
- please add subsection 5.1 ENERGY-OBJECT-MIB
  before "The ENERGY-OBJECT-MIB MIB module ..."

(2) Page 6 (grammar)
- parenthetic clauses cannot be normative in standard English
- please change
"This compliance requires that the
following 3 MIB objects from ENTITY-MIB [RFC6933]
(entPhysicalIndex, entPhysicalName and entPhysicalUUID) MUST be
implemented."
  to
"This compliance requires that the
following 3 MIB objects from ENTITY-MIB [RFC6933] MUST be
implemented:  entPhysicalIndex, entPhysicalName, entPhysicalUUID."

(3) Page 7 (missing word)
- please change "provide the log the" to "provide the log of the"

(4) Page 7 (missing legend info)
- please add a sentence explaining each of "rwn" for object trees
  (read, write, notify).

(5) Page 8 (inconsistent usage)
- please change "The powerAttributesMIB consists ..."
  to "The POWER-ATTRIBUTES-MIB consists ..."

(6) Page 8 (readability)
- please add subsection 5.2 POWER-ATTRIBUTES-MIB
  before "The POWER-ATTRIBUTES-MIB consists ..."

(7) Page 9 (cardinality)
- please change "A UML representation of ... are presented."
  to "A UML representation of ... is presented below."

(8) Page 11 (grammar)
- please change "In this table, the context ... are specified."
  to "In this table, the contexts ... are specified."

(9) Page 13 (grammar)
- please change "The difference between ... can be attributed that"
  to "The difference between ... indicate that"

(10) Page 14 (poor wording)
- please "There are currently three Power State Sets advocated:"
  to "There are currently three Power State Sets defined:"

(11) Page 14 (readability)
- please change "raised to the power of the scale."
  to "raised to the power of the unit multiplier."

(12) Page 15 (poor wording)
- please change "adheres closely to"
  to "is technically aligned with"

(13) Page 15 (grammar)
- please change "It is relevant to measure energy and demand only"
  to "It is only relevant to measure energy and demand"

(14) Page 18 (poor wording)
- explicit numeric values should not appear in informative text
- please change "active (value 1)" to "active"

(15) Page 19 (missing comma)
- please change "eoEnergyParametersIndex which"
  to "eoEnergyParametersIndex, which"

(16) Page 19 (grammar)
- please change "period, i.e. a month,"
  to "period, e.g., a month,"

(17) Page 20 (extra comma)
- please change "value(s) of ,eoPowerStateIndex,"
  to "value(s) of eoPowerStateIndex,"

(18) Page 20 (poor wording)
- please change "It is foreseen that most"
  to "It is probable that most"

(19) Page 20 (extra space, extra comma, missing word)
- please change "Energy Object ( entPhysicalIndex), by the"
  to "Energy Object (entPhysicalIndex) and by the"

(20) Page 20 (cardinality)
- please change "which have their own"
  to "which has its own"

(21) Page 20 (poor wording)
- please change "must be discovered thanks to the"
  to "must be discovered via the"

(22) Page 20 (poor wording)
- please change "monitor the power attributes thanks to the"
  to "monitor the power attributes via the"

(23) Page 21 (poor wording)
- please change "this MIB proposes a customized power scale"
  to "this MIB supports a customized power scale"

(24) Page 22 (poor wording)
- please change "doing the proxy between"
  to "implementing the proxy between"

(25) Page 22 (poor wording)
- please change "thanks to PhysicalIndexOrZero"
  to "via the PhysicalIndexOrZero"

(26) Page 22 (ambiguity)
- please change "The RFC introduces"
  to "RFC 3621 introduces"

(27) Page 23 (poor wording)
- please change "doing the proxy between"
  to "implementing the proxy between"

(28) Page 23 (poor wording)
- please change "thanks to new PethPsePortIndexOrZero"
  to "via the new PethPsePortIndexOrZero"

(29) Page 24 (poor wording)
- please change "is copied over in"
  to "is copied over into"

(30) Page 25 (missing capital letter)
- please change "[EMAN-AWARE-MIB]. while the PC"
  to ""[EMAN-AWARE-MIB]. While the PC"

(31) Page 25 (extra space)
- please change "UUID 1000:57 ".
  to "UUID 1000:57".

(32) Pages 26 and 27 (page break across figure)
- please insert a page break before Figure 6 (to avoid widowed
  lines)

(33) Page 27 (cardinality)
- please change "The notion of identity"
  to "The notions of identity"

(34) Page 27 (grammar)
- parenthetic clauses cannot be normative in standard English
- please change
"should be supported which requires 3 MIB objects
(entPhysicalIndex, entPhysicalName and entPhysicalUUID ) MUST be
implemented."
  to
"should be supported which requires 3 MIB objects MUST be
implemented: entPhysicalIndex, entPhysicalName and entPhysicalUUID."

(35) Page 30 (ambiguity)
- in DESCRIPTION clause, please change
"This table sparse extension of the eoTable"
  to
"The eoMeterCapabilitiesTable is a sparse extension of the eoTable"

(36) Page 32 (cardinality)
- please change "This object use a BITS syntax  and indicate"
  to "This object uses a BITS syntax and indicates"

(37) Page 33 (extra period)
- please change "fixed number of AC cycles.  ."
  to "fixed number of AC cycles."

(38) Page 34 (ambiguity)
- please change "The eoPowerNameplate is widely used"
  to "The nameplate power is widely used"

(39) Page 35 (misuse of, misnamed, and incorrect explicit values)
- please change "actual(2), estimated(3) or presumed (4)."
  to "actual, estimated, or static."
- please change "is not presumed(4) or estimated(3)"
  to "is not estimated or static"

(40) Page 36 (misuse of, misnamed, and incorrect explicit values)
- please change "alternating current AC(1),"
  to "alternating current 'ac',
- please change "direct current DC(1),"
  to "direct current 'dc',"
- please change "unknown(3)."
  to "unknown."

(41) Page 36 (poor object naming)
- "eoPowerOrigin" is a really a boolean
- it would be better named "eoPowerOriginRemote" with a default
  value of 'false' (i.e., self or local)

(42) Page 36 (misuse of explicit values)
- see above comment about "eoPowerOrigin" name - below may not apply
- please change "self(1)"
  to "self"
- please change "remote(2)"
  to "remote"

(43) Page 37 (missing period)
- please change "transition Alternatively, this"
  to "transition.  Alternatively, this"

(44) Page 38 (poor wording)
- please change "this table extends to return"
  to "this table also includes"

(45) Page 39 (ambiguous special value)
- this is a signed 32-bit object (Integer32)
- please change "0xFFFF" (16-bits)
  to "0xFFFFFFFF" (maximum negative 32-bits)

(46) Pages 39 and 40 (cardinality)
- please change "hundredth of second"
  to "hundredths of seconds"

(47) Page 40 (missing word and grammar)
- please change "only sense for Energy Objects that"
  to "only makes sense for Energy Objects with"

(48) Page 41 (grammar - comma should be semi-colon)
- please change "measurement is applied, the same index"
  to "measurement is applied; the same index"

(49) Page 41 (cardinality)
- please change "depending on the capability of"
  to "depending on the capabilities of"

(50) Page 41 (cardinality)
- please change "hundredth of seconds"
  to "hundredths of seconds"

(51) Page 41 (missing rationale for default value)
- please explain why "90000" (15 minutes) is the default value of
  eoEnergyParametersIntervalLength

(52) Page 42 (missing aging/pruning algorithm rationale)
- please explain (perhaps more in preface before MIB?)
  the exception to aging of old entries described in
  eoEnergyParametersIntervalNumber (I couldn't understand this)

(53) Page 43 (cardinality)
- please change "hundredth of seconds"
  to "hundredths of seconds"

(54) Page 43 (missing default value rationale)
- please explain the default value of "1000" (1 second)
  for eoEnergyParametersSampleRate

(55) Page 43 (underspecified RowStatus usage)
- please explain why 'notReady' or 'createAndWait'
  in eoEnergyParametersStatus should delete usage data
  (this is not obvious to me)

(56) Page 45 (extra space)
- please change "eoEnergyMaxProduced ."
  to "eoEnergyMaxProduced." (in eoEnergyUnitMultiplier)

(57) Page 46 (ambiguity)
- please change "indicates a percentage value,"
  to "indicates an accuracy," (in eoEnergyAccuracy)

(58) Page 47 (poor wording)
- please change "This variable indicates"
  to "This object controls" (in eoPowerEnableStatusNotification)

(59) Pages 48 and 49 (grammar - five occurrences)
- parenthetic clauses cannot be normative in standard English
- please change
"of 3 MIB objects (entPhysicalIndex,
entPhysicalName and entPhysicalUUID)."
  to
"of 3 MIB objects: entPhysicalIndex,
entPhysicalName, and entPhysicalUUID."
  (in energyObjectMIBFullCompliance, energyObjectMIBEnergyTableGroup,
  energyObjectMIBEnergyParametersTableGroup,
  energyObjectMIBMeterCapabilitiesTableGroup, and
  energyObjectMIBReadOnlyCompliance)

(60) Page 49 (ambiguity)
- please explain why only 'read-create' and 'read-only' are
  described, but 'read-write' is not described (useful for
  statically allocated tables, using 'notInService' for a toggle)

(61) Page 54 (inconsistent wording)
- a requirement has to be paired with MUST (capitalized)
- a recommandation has to be paired with SHOULD (capitalized)
- please change "As a requirement ... should be implemented."
  to "As a requirement ... MUST be implemented."
  (in DESCRIPTION clause)

(62) Page 54 (grammar)
- parenthetic clauses cannot be normative in standard English
- please change
"of 3 MIB objects (entPhysicalIndex,
entPhysicalName and entPhysicalUUID)."
  to
"of 3 MIB objects: entPhysicalIndex,
entPhysicalName, and entPhysicalUUID."
  (in DESCRIPTION clause)

(63) Page 54 (grammar)
- please change "This table defines power attributes"
  to "This table contains power attributes"
  (in eoACPwrAttributesTable)

(64) Page 56 (spelling error)
- please change "Ampheres"
  to "amperes" (lowercase)
  (in eoACPwrAttributesAvgCurrent)

(65) Page 57 (extra space)
- please change " watts"
  to "watts"
  (in eoACPwrAttributesTotalActivePower)

(66) Page 57 (spelling error)
- please change "A mesured value"
  to "A measured value"
  (in eoACPwrAttributesTotalReactivePower)

(67) Page 60 (spelling error)
- please change "Ampheres"
  to "amperes" (lowercase)
  (in eoACPwrAttributesPhaseAvgCurrent)

(68) Pages 64 and 65 (grammar)
- parenthetic clauses cannot be normative in standard English
- please change
"of 3 MIB objects (entPhysicalIndex,
entPhysicalName and entPhysicalUUID)."
  to
"of 3 MIB objects: entPhysicalIndex,
entPhysicalName, and entPhysicalUUID."
  (in powerAttributesMIBFullCompliance)

(69) Page 72 (unsafe allocation of new MIB objects)
- please explain why Expert Review (rather than a new RFC)
  is allowed for defining new MIB objects - seems inherently unsafe
  (in section 13 IANA Considerations)

(70) Page 72 (garbled sentence)
- please rewrite sentence containing "and will, as a consequence"
  (in section 13.1 IANA Registration of new Power State Set)

Cheers,
- Ira

Ira McDonald (Musician / Software Architect)
Co-Chair - TCG Trusted Mobility Solutions WG
Chair - Linux Foundation Open Printing WG
Secretary - IEEE-ISTO Printer Working Group
Co-Chair - IEEE-ISTO PWG Internet Printing Protocol WG
IETF Designated Expert - IPP & Printer MIB
Blue Roof Music / High North Inc
http://sites.google.com/site/blueroofmusic
http://sites.google.com/site/highnorthinc
mailto: [email-masked]
Winter  579 Park Place  Saline, MI  48176  734-944-0094
Summer  PO Box 221  Grand Marais, MI 49839  906-494-2434