W3C home > Mailing lists > Public > www-qa-wg@w3.org > March 2005

[SpecGL] Toc/Numbering Proposal

From: Karl Dubost <karl@w3.org>
Date: Wed, 9 Mar 2005 18:04:15 -0500
Message-Id: <22046daa61f0fb2ee6aa6a674b9cf663@w3.org>
To: 'www-qa-wg@w3.org' <www-qa-wg@w3.org>
Hi QA WG,
	There's almost no way to refer properly and simply to the requirements 
or Good Practices without making either a very long numbering.
			2.1.1.1 Req A
or instead to say that they have their own sequence number. Thinking 
about the ICS or how people will use it for checking conformance, they 
will go through the list of
	Req 01
	Req 02
	Req 03
     ...
And then
	GP  01
	GP  02
	GP  03
     ...

Which means I come with a possible table of contents which looks like 
that.


Table of contents
1. Introduction
  1.1  Scope
  1.2 Goals and Motivation
  1.3 Why Specification Guidelines?
  1.4 Audience of this document
  1.5  About this document
2. Guidelines
  2.1 Specifying Conformance
   2.1.1 The conformance clause is essential
     Req 01 Include a conformance clause.
     GP  01 Define the specification's conformance model in the
            conformance clause.
     GP  02 Specify in the conformance clause how to distinguish
            normative from informative content.
   2.1.2 Specify how to make conformance claims
     GP  03 Provide the wording for conformance claims.
     GP  04 Provide an Implementation Conformance Statement Proforma.
     GP  05 Require an Implementation Conformance Statement as
            part of valid conformance claims.
  2.2 Setting up ground rules
   2.2.1 Scope
     Req 02 Define the scope.
     GP  06 Provide examples, use cases, and graphics.
   2.2.2 What needs to conform?
     Req 03 Identify who or what will implement the specification.
   2.2.3 Normative (and non-normative) references
     Req 04 Make a list of normative references.
     GP  07 Do systematic reviews of normative references and
            their implications.

etc....

	◦ 	 2.3 Defining and using terminology
	◦ 	 2.4 Managing Variability
	◦ 	 2.5 Do Quality Control
	• 	3. Conformance to this document
	◦ 	 3.1 Conformance criteria
	◦ 	 3.2 Normative Parts
	◦ 	 3.3 Specification Guidelines Extensibility
	◦ 	 3.4 Conformance claims
	• 	5. Acknowledgments
	• 	6. References
	◦ 	6.1 Normative References
	◦ 	6.2 Informative References
	◦ 	6.3 Further Reading
	• 	7. Glossary
	• 	Appendix A: Publication Workflow
	◦ 	A.1 Define an internal publication and review process.
	◦ 	A.2 Do a systematic and thorough review.
	◦ 	A.3 Write sample code or tests.

-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager
*** Be Strict To Be Cool ***

Received on Thursday, 10 March 2005 00:03:53 GMT

This archive was generated by hypermail 2.2.0 + w3c-0.30 : Thursday, 9 June 2005 12:13:19 GMT