Dear QAWG,
Thank you for addressing my comments on the Spec Guidelines. Below are my acknowledgments to how my issues were addressed. I have no objections, but I do have some suggestions.
This document closes the loop after the QA Working Group's (QAWG) response to comments on the Last Call Working Draft of QA Framework: Specification Guidelines Please note that the table below is for Specification Guidelines only.
The "Status" column indicates QAWG's disposition of the issue:
accepted: originator's suggestion (if any) was accepted substantially as proposed.
accepted with modifications: QAWG accepts that originator's issue is valid, but we implemented something else than what (if anything) was suggested - originators, please check that it does solve your issue.
not accepted: originator's comments and/or suggestions were not accepted — originators, please check that you accept QAWG's explanation and rationale.
Last update: $Date: 2003/09/18 21:13:02 $
| Issue # | Originator | Description | Resolution | Status | Originator's reply |
|---|---|---|---|---|---|
| LC-26 | Ian Jacobs | Multiple CPs - It is not applicable | QAWG appreciates the utility of the "normative exclusion" concept in the complex conformance landscape of UAAG 1.0. For the few and simple occurrences of the "not applicable" usages in SpecGL, QAWG considers that it is cleaner and clearer not to introduce a new concept and terminology such as "normative exclusion". Resolved: no change. | not accepted | Ok |
| LC-35 | Ian Jacobs | Section 3.2 Extensibility | Although CP9.3 may be redundant, the redundancy doesn't hurt here. Not every reader is going to logically connect the dots, as has the commentor. Therefore QAWG believes that CP9.3 should remain as is. | not accepted | Please add a cross reference from section 3.2 to checkpoint 9.3 (6.2 in 12 Sep 2003 draft). Also, the title to G6 is awkward; please change to "Set expectations about extensions" or similar. |
| LC-37 | Ian Jacobs | CP 9.3 | Although CP9.3 may be redundant, the redundancy doesn't hurt here. Not every reader is going to logically connect the dots, as has the commentor. Therefore has resolved to keep CP9.3 as is. | not accepted | See LC-35 |
| LC-23 | Ian Jacobs | CP 1.4 vague | Resolved in favor of modified Alternative 2. The discussion and breakdown by category will be done in Spec Examples & Techniques (SpecET). But the Discussion of CP1.4 (now CP1.3) will mention the concept raised by comment originator (that different kinds of specification categories require different particular associated kinds of examples), and gives a brief "for example." See draft revised text. | accepted with modifications | I disagree that my comment was accepted with modifications since the checkpoint has not changed. I will not object to the document moving forward, but I believe you will find readers asking the question "How do I know when I've satisfied the checkpoint? What is enough for conformance?" |
| LC-29.1 | Ian Jacobs | questions and suggestions: In general, specifications make functional requirements. In some cases, it may be necessary to make a performance requirement. How should that be handled? | 20030714 telecon directed that it be resolved as indicated in ungrouped-issue proposals: if performance requirements are within the scope of the standard, and they presented the same as any other conformance requirement -- e.g., using RFC2119 keywords -- then there would not seem to be any issue. For conformance purposes, they would not need any special handling. (No changes to SpecGL.) |
accepted with modification | While I agree that a performance requirement might not require special handling w.r.t. conformance, I still think that such requirements are special. No further discussion is necessary at this time. | ||
| LC-29.2 | Ian Jacobs | questions and suggestions: In UAAG 1.0, we realized that for some of our configuration requirements, it didn't matter whether the user agent offered the desired configuration or didn't implement the functionality in the first place. E.g., we decided that it was ok for a user agent to not support blinking at all, or, if blinking is implemented, to offer a configuration to turn it off. However, in other cases, the configurability was "just as important" as the functionality to be configured. Authors should consider these when they specify configuration options. | 20030714 telecon directed that it be resolved as indicated in ungrouped-issue proposals: Since SpecGL 1.0 has not gone to such a level of detail as addressing configuration options, we are unsure how this comment would affect SpecGL. Note that we (QAWG) have decided that the scope of SpecGL 1.0 should be limited to the most critical and basic topics. This could be added to requirements for SpecGL 2.0. It could also be mentioned, possibly, in SpecET (Examples & Techniques). If Originator thinks that this topic fits under one of SpecGL's existing checkpoints, then perhaps he would be interested to make a contribution, to be put into SpecET. The SpecGL scope has been clarified to indicate the "basic and critical" scope of SpecGL 1.0. See draft revised text. |
accepted with modification | Ok | ||
| LC-29.3 | Ian Jacobs | questions and suggestions: It might be valuable for a specification to explain how to include its requirements in another specification. This is not the same as explaining how to reference the spec, or how to claim conformance to it. | Discussed at 20030707 telecon. We (QAWG) have decided that the scope of SpecGL 1.0 should be limited to the most critical and basic topics. We think that this topic has merit, but is more advanced and detailed than we are dealing with in SpecGL 1.0. It could be added to requirements for SpecGL 2.0. Alternately or in addition, it could also be mentioned in SpecET (Examples & Techniques). If Originator thinks that this topic fits under one of SpecGL's existing checkpoints, then perhaps he would be interested to make a contribution, to be put into SpecET. The SpecGL scope has been clarified to indicate the "basic and critical" scope of SpecGL 1.0. See draft revised text. |
accepted with modification | Ok | ||
| LC-29.5 | Ian Jacobs | questions and suggestions: I think that more could be stated about useful ways of allowing extensibility. See, for example, how CSS (forward-compatible parsing), XML, and HTTP handle this. What should be avoided? Is the general practice of "ignore what you don't know" a good idea or a big mistake? | Resolved at 20030505 telecon, as part of the extensibility issue group resolution. This should not be covered in SpecGL, but it ought to be covered in the SpecET material on extensions. SpecET should illustrate numerous kinds of extensions -- some that have serious interoperability impacts, some that mitigate the impacts, some approaches that might be considered "useful", etc. Also, QAWG discussion sees some problems with examples such as CSS "forward compatible parsing" -- it opens up the ill-defined topic of what is an unknown extension versus what is corrupted or erroneous content. This has been added to the SpecET queue. |
accepted with modification | Ok. By the way, the TAG is working on a finding related to extensibility and versioning (not yet available). | ||
| LC-30 | Ian Jacobs | Profile, module, level | See the comprehensive solution for the profiles/modules/levels issue group. Agreed to clarify concepts with better definitions and discussion, and to merge the three separate guidelines into a single guideline. However the 3 individual concepts will be kept as separate DoVs within the merged guideline, and will be dealt with independently in the appropriate checkpoints. See draft revised text. | accepted with modifications | Ok | ||
| LC-32 | Ian Jacobs | 4. Definitions | Since the term is not used anywhere in SpecGL, the empty definition is removed from SpecGL. (And a definition will be added to "QA Glossary".) See draft revised text. | accepted with modifications | Ok | ||
| LC-36 | Ian Jacobs | Section 3.1 Normative sections | SpecGL uses a focused definition of normative -- normative stuff is directly connected to conformance requirements -- that is narrowly applied. By this definition and its application, things like Glossary definitions ("5. Definitions") are not normative. SpecGL has clarified what's normative in "Normative parts" in "4. Conformance". Also, in "1.6 Usage of terminology", it is clarified that defined terms, when used in SpecGL, have the meanings given in the definitions. See draft revised text. | accepted with modifications | The WGs response seems to avoid the question. Terms that are used in (normative) requirements that are defined in the glossary (i.e., where the English language meaning may not suffice) should probably also be normative. Some terms in the glossary may not be normative, but those whose definitions affect conformance should be normative. |
| LC-22 | Ian Jacobs | CP 2.3 placement of Checkpoint | This contradiction has been removed, as a part of revision of the Introduction chapter, the addition of a "Concepts" DoV chapter, and the reorganization and consolidation of the Guidelines. See draft revised text. | accepted | no reply - default OK |
| LC-24 | Ian Jacobs | Introduction, Sect 1.4 | This has been changed as suggested. See draft revised text. | accepted | no reply - default OK |
| LC-25 | Ian Jacobs | Introduction: scope and goals | Agreed, it has been deleted. See draft revised text. | accepted | no reply - default OK |
| LC-27 | Ian Jacobs | Typos, grammar, etc. | These have all been fixed as suggested. | accepted | no reply - default OK |
| LC-28 | Ian Jacobs | document organization suggestions | Agreed, this has been done. | accepted | no reply - default OK |
| LC-29.4 | Ian Jacobs | questions and suggestions: It might be valuable to explain some desirable characteristics of a specified technical requirement: Mutual independence from other requirements Expresses a minimal requirement Distinguish and label: requirements, exceptions to those requirements, necessary and/or sufficient techniques for satisfying those requirements. | Discussed and resolved at 20030623 telecon. Agreed that it is useful to discuss some attributes of well-written conformance requirements. Some verbiage has been added to the introductory text of GL7 (new number). More extensive material may be added to SpecET (contributions would be welcome!). See draft revised text. |
accepted | no reply - default OK |
| LC-29.6 | Ian Jacobs | questions and suggestions: A spec should clearly indicate which illustrations (e.g., images) and examples are normative, if any. | 20030714 telecon directed that it be resolved as indicated in ungrouped-issue proposals: agreed. The wording of CP13.2 has been adjusted to include all sorts of normative content. See draft revised text. |
accepted | no reply - default OK |
| LC-31 | Ian Jacobs | general | Thanks for the useful feedback. (No issue.) | accepted | no reply - default OK |
| LC-33 | Ian Jacobs | 4. Definitions | The language has been clarified and made more specific. See draft revised text. | accepted | no reply - default OK |
| LC-34 | Ian Jacobs | Section 3.4 Conformance definition | The second sentence is dropped as suggested, and the wording of the first sentence is tuned. See draft revised text. | accepted | no reply - default OK |
| LC-38 | Ian Jacobs | CP 9.1 and 9.2 combine | Agreed, CP9.1 and 9.2 have been combined (into new CP6.1). See draft revised text. | accepted | no reply - default OK |
| LC-39 | Ian Jacobs | CP 8.4 policies for discretionary choices | 8.4 has been kept (now CP 5.4), broadened to "items" instead of "choices", and final text (derived from the new proposal) has been revised and clarified by SpecGL editors. See revised text. | accepted | no reply - default OK |
| LC-40 | Ian Jacobs | GL7 add obsolete features | Per LR proposed resolution: add a definition of obsolete, add a new checkpoint about obsolete features, add language to GL7 (new GL4) verbiage. See draft revised text. | accepted | no reply - default OK |
| LC-41 | Ian Jacobs | CP 4.4 derived profile | "Derived profile" is now defined in the new chapter "2. Concepts", and has been added to "Definitions", and that definition is linked from appropriate places in the guidelines. See draft revised text. | accepted | no reply - default OK |
| LC-42 | Ian Jacobs | GL3: contradiction? regarding examples | While the verbiage in GL3 is informative, versus the normative requirements of CP1.4, nevertheless the text in question has been revised, removing "possibly", to avoid any apparent conflict with "MUST provide examples". See draft revised text. | accepted | no reply - default OK |