AEP 1.0 FTF Avatar
  1. OMG Issue

AEP — Specification should be more prescriptive

  • Key: AEP-17
  • Status: closed  
  • Source: Object Management Group ( Andrew Watson)
  • Summary:

    The specification should be more prescriptive. A document like this must tell implementers exactly what they must do to create a conforming implementation. Mandatory parts of the specification shall therefore use the word "shall". Words like "should", "can" or "will" are too vague, and do not comply with the ISO directives that OMG follows; as the OMG RFP template says (section 4.9.1):

    'The key words "shall", "shall not", "should", "should not", "may"
    and "need not" shall be used as described in Part 2 of the ISO/IEC
    Directives [ISO2]. These ISO terms are compatible with the same terms in
    IETF RFC 2119 [RFC2119]. However, the RFC 2119 terms "must", "must
    not", "optional", "required", "recommended" and "not recommended"
    shall not be used (even though they are permitted under RFC2119).'

    Those ISO directives can be found here:

    [ISO2] ISO/IEC Directives, Part 2 – Rules for the structure and drafting of
    International Standards

    Please check every instance of the words "will" (41 instances), "must" (6 instances), "could" (2 instances) to see if they should be replaced by "shall", and check every "should" (7 instances) and "may" (21 instances) to see if they're being used as per ISO Directives Part 2.

  • Reported: AEP 1.0b1 — Wed, 6 Apr 2016 07:14 GMT
  • Disposition: Resolved — AEP 1.0
  • Disposition Summary:

    Made spec more prescriptive

    make wording more prescriptive throughout spec

  • Updated: Tue, 11 Oct 2016 14:46 GMT