Proposed text for SpecGL LC comments


A current working version of SpecGL is available at:
We are still working on the document, but as you can see much has been done 
and is still being done.  Things that still need to be done include:
1. GL8 - to review what DM drafted, modify his 8.4 and maybe other parts 
and put it into the document
2. GL9 - there were several comments and changes to make.  I am also 
supposed to add a new CP
3. Reorder and Merge:  GL 13, 10/3, 11/12  and make appropriate 
modification to text
4.  Modify section 3.2 Extensions - in crete we said that A+ (doing A and 
some AA and some AAA) was not an extension.

Below are many of the LC issue resolutions and the text that has been 
incorporated.  Any comments?


LC93, 94, 48, 46 (to make it clearer what we are referring to and that the 
list is non-exhaustive
-- CP2.2  Added an explanation
The list of classes of products (Table 2) enumerate the most common classes 
of products.  If your class of product matches one or more terms in the 
list, then use the terms in the list. If no term is an appropriate match, 
then define your own.
-- CP2.3  Added an explanation and clarification in the rationale
Understanding the kind of specification that is being written, contributes 
towards understanding the target of the specification, i.e., the applicable 
classes of products.
  Moreover, it helps both the author(s) and readers understand the scope of 
the specification and its focus.   The list of specification categories 
(Table 1) enumerate the most common categories of specifications.  If your 
specification matches one or more a categories in the list, then use those 
categories.  If no category is an appropriate match, then define your own.

LC 23, 75.1, 92, 79   Examples, use cases etc.
Clarified 1.2 and 1.4, moved 1.3 to follow 1.4
Modifications to CP1.2
- changed title: Illustrate scope
- modified rationale, now reads:  a set of broad examples and/or use cases 
helps to clarify the specification's scope. It gives the reader additional 
information in understanding the purpose, audience, and applicability of 
the specification. These examples and use cases may be included in the 
specification or may be in a separate document referenced by the 
specification.  It is up to the Working Group to determine what the best 
way to illustrate the scope, i.e., to use examples or use cases or both.

Modifications to CP 1.4 (now becomes new CP1.3)
- changed title: Illustrate functional details
- modified rationale, now reads:  it is difficult to understand some 
concepts, behavior, or functionality without informative interpretations to 
aid the reader. These examples are specific in nature and are use to make 
clear a concept, behavior, interaction, etc. that is innately complex or 
for which the WG has had to explain to its members or the public.

LC issues regarding CP1,2, 1.3, 1.4  closed
--LC 109  merge CP1.3 with CP1.2
Done.  Added 'Use cases are a valuable way to describe the different ways a 
specification can be used' to explanation of CP1.2
--LC LC 23  be more specific for 'provide examples'
Added:  The nature of the specification will influence the type of examples 
that are relevant.  For example, for markup specifications, provide at 
least one example of each markup construct; for transformation 
specifications, illustrate each transformation capability with an example 
showing input and output.
--LC 75.1  reorder CP according to Priority
Moot.  CP1.3 deleted.
--Note: 79 and 92 already closed.  77.ET-2 needs to be implemented in ET

This completes LC 96 and 42: GL3-policy
--LC96:  clarified universal requirements
New Rationale: the reader must be able to recognize any minimum functionality,
complexity, or support that applies to conforming products of a specific
class. These minimum requirements can be considered a starting point for a
checklist to be used by a team developing a conforming product.  It helps
the reader find these requirements by presenting them as a collection, in
one place rather than distributed throughout the document.  This collection
may be derived from the distributed requirements and may apply to a single
class of product or across classes of products.

--LC 42 (already done --  Removed 'possibly') Note, when GL3 is combined 
with GL10, some of this may go away.

FROM LH's Ungrouped issues email, 6 July
LC17: can deprecated feature be distributed
Added Rationale: It helps the reader find these requirements by presenting 
them as a collection, in one place rather than distributed throughout the 
document. This collection may be derived from the distributed requirements 
and may apply to a single class of product or across classes of products.

LC20  single section for universal rqts?
Moot.  Clarified CP3.1 as a collection.

If performance requirements are part (i.e., requirements) of a 
specification, then they are like all other conformance 
requirements.  Else, they are outside the scope of conformance.

The desirability of some requirements vs other requirements can be 
considered and handled as DoV. The SpecGL doesn't specifically address the 
idea that some requirements are more important than other.  Although no 
specific guidance is given, it isn't precluded either.  This may be an area 
to address in a future version of SpecGL.

LC - 29.3
Interesting points, but outside scope.

LC34 Section 3.4 conformance definition.
Modified as per proposal  replaced 'individual' with 'mandatory'. Deleted 
second sentence.

LC64  CP 3.2 conf terms defined
Done previously, modified/clarified ConReq: 'any conformance concepts used 
in the specification MUST be defined, either by reference or by including 
the definition in the text.'

LC73.7 change Priority of CP10.2
Accepted  changed to P1

LC77.SG-2 (Use standard headings)
Agree that this is a good guide and we will adhere to it, as best we can, 
recognizing that each Framework document may have unique chapters.  All 
documents will have the same core headings and in the same order:  Intro, 
Guidelines, Conformance, Definitions (if applicable), Acknowledgements, 
References, Change History.
No changes to SpecGL needed.

LC78 template for conformance claims
Agreed, good idea.  Will be implemented as resources are available.
No changes to SpecGL needed.

  LC19  clarify [profile] experience
Added to explanation:  Previous experience in W3C (e.g., creation of 
WebCGM) and by other organizations in creating derived profiles or defining 
rules for profiles

LC22 placement of CP2.3 with respect to introduction's categorization of 2 
types of guidelines
Yes, a part of CP2.3 deals with where the information needs to be 
placed.  Due to many changes, this intro text may need to be rewritten  For 
now, I've deleted the mention of which Guidelines fall into which general 
type.  It may be that a guideline falls into both categories.
(temporarily closed, but should revisit)

LC25 scope/goals of Sec1.1
Deleted from Sec 1.2  (this was done prior to today, july 16).  I think 
that it is no longer needed since we have the use cases, which cover the 
intent of this text.

LC28 use stylesheets to hide links
???. I think the idea is to have a collapsible ToC, which expands when you 
link to a section and that there be a option for a printable version of the 
document, etc.
Nothing to edit in SpecGL

LC29.6 indicate normatively of examples and illustrations.
Yes, will do this.  Currently, there are no normative illustrations or 
examples.  Do we need to explicitly label examples/illustrations as 
informative  I don't think we do.

LC88 Reformat bullet list.
Comment references CP1.3, which doesn't have a bullet list.  I think this 
refers to the 8 items in the DoV.
No objection from me to use something other than bullets.

LC73.8- add rationale to CP13.3
Rationale: Being consistent and following established conventions and W3C 
editorial practices will enhance the readability and comprehensibility of 
the specification.

LC-8 Checkpoint 1.1 is wooly
Reworded Title: Include a scope statement.
Reworded the explanation. The scope describes the areas covered by the 
specification, thereby indicating the intent or applicability of the 
specification. It does not specify requirements and is worded as a series 
of statements of fact.

LC61 done (as result of other LC issues)
new class called 'specification' added

Added definition for 'derived profile', since no one (answered my email 
and) sent one.
derived profile
a profile that is created from a set of profile rules, where these profile 
rules provide instructions for buiding (i.e., defining profiles) and the 
rules are defined in a specification.

LC14 clarify CP14.1 separate document for TA
Clarified and Modified GL and CP explanations-In GL explanation, modified 2 
sentence: It is derived from the specification's requirements and provides 
a normative foundation from which test cases can be built.
--In GL explanation added at the end:  It is recommended that test 
assertions be available by the time a specification enters Proposed 
--In CP14.1 modified explanation: In order to enable traceability from the 
tests back to the test assertions, use a mechanism for making explicit test 
assertions in the specification. The list of test assertions can be 
included in the specification or in a separate document that is referenced 
by the specification. Test assertions may be developed by the specification 
authors, others members of the WG or people external to the WG.

LC29.4 characteristics of technical requirements
The suggestion of desirable characteristics, e.g., independence, minimal, 
distinguish and label  are exactly what we define/describe for TAs.  Do we 
need to do anything to close this LC  other than acknowledge the comment 
and say that we advocate this for TAs, which are the specific requirements 
from which tests would be built?

Received on Tuesday, 29 July 2003 11:31:10 UTC