Re: Wording for Functional Profiles in Conneg

I have created a PR that implements these changes as requested plus some other, previously requested, edits:

https://github.com/w3c/dxwg/pull/1121


Nick


On 9/10/19, 10:54 am, "Karen Coyle" <kcoyle@kcoyle.net> wrote:

    All,
    
    At the meeting today we resolved to finalize the wording for functional
    profiles in Conneg, with the goal of making clear the status of the
    profiles described in the document. I took an action to note the current
    wording, which will be reviewed by the group (in particular by Annette
    who had questions in this area).
    
    The Functional Profiles are described in section 7 of the document. [1]
    The opening paragraph of section 7.1 [2] states:
    
    "This section describes functional profiles of this specification's
    Abstract Model which are implementations of it in different
    environments. These functional profiles are formally identified in § 7.2
    Conformance to Functional Profiles and are to be used as conformance
    targets for specific implementations of systems within different
    environments wishing to conform to this specification."
    
    kc: I think that the phrase "are to be used" implies that these profiles
    are required. Perhaps changing this to "may be used" would be more
    accurate. In fact, the whole could be edited as:
    
    "This section illustrates a few conformant functional profiles of this
    specification's Abstract Model for different system environments. These
    functional profiles are formally described in § 7.2 Conformance to
    Functional Profiles and may be used within different environments
    wishing to conform to this specification. Implementation of the profiles
    illustrated here is not mandatory; any profile that conforms to the
    Abstract Model fulfills conformance to this document."
    
    There is a note in section 7.1 that reads:
    
    "Implementers of Content Negotiation by Profile need not ensure systems
    conform to multiple functional profiles of this specification. They need
    only conform to the functional profile(s) relevant to their environment.
    In some cases, for example the Query String Argument-relevant human
    browser environment, there is a choice of more than one functional
    profile. Since all functional profiles of this specification themselves
    must conform to this specification, by design, conformance to any
    functional profile guarantees conformance to the specification."
    
    kc: Again, the third sentence here makes it sound like these are THE
    functional profiles that one must implement. I suggest using this note
    to clarify that these are only a sample of possible profiles:
    
    "The functional profiles provided here are conformant with the abstract
    model. Systems may implement one or more of the profiles provided in
    this document or may develop other functional profiles that conform to
    the abstract model. Conformance to one of the profiles provided here
    guarantees conformance to the abstract model, but conformance can be
    achieved with other functional profiles. Implementers of Content
    Negotiation by Profile need not ensure systems conform to multiple
    functional profiles of this specification, they need only conform to the
    functional profile(s) relevant to their environment."
    
    The second paragraph of section 7.2 [3] reads:
    
    "Figure 2 is not an exhaustive list of functional profiles of this
    specification and users MAY make additional functional profiles for
    different environments, as described in the previous section."
    
    kc: The use of "additional" here sounds like one must implement THESE
    profiles PLUS others. Changing from "additional" to "other" removes that
    ambiguity.
    
    Is this sufficient to clarify the optional nature of the functional
    profiles? It would be great if some of you would read through the
    remainder of section 7 and see if you find other areas that could use
    editing. Also, I realize that there is redundancy in the edits I have
    made; if it seems to be too much we can try to reduce that.
    
    Thank you,
    
    kc
    [1] https://w3c.github.io/dxwg/conneg-by-ap/

    [2] https://w3c.github.io/dxwg/conneg-by-ap/#functional-profiles

    [3] https://w3c.github.io/dxwg/conneg-by-ap/#conformance-profiles

    -- 
    Karen Coyle
    kcoyle@kcoyle.net http://kcoyle.net

    skype: kcoylenet

Received on Wednesday, 9 October 2019 11:47:33 UTC