SpecLite -- checklist
- Author:
- Lofton Henderson
- Date/version:
- 06 March 2004
This is a companion first cut to SpecLite -- template(s). The template(s) were sketched first -- providing document conformance specification that we think would be exemplary good practice -- and here are some guidelines (GL) and checkpoints (CP) that might correspond to and lead to such conformance specifications.
I have not addressed whether we ultimately want to have GL & CP still, or "Principles" and "Good Practice", or whatever. The goal (this early draft) is to show what a reasonable set of "rules" might look like.
Lots of CPs get deleted (some more possibly could). Some get merged. The number of surviving rules is less than 1/3 of CR SpecGL. Lots of good stuff that we previously worked out in detail, and presumably that we still believe in, gets deleted from this "Lite", minimized rule set.
Definition of "deleted" -- I have speculated a bit what we might do with "deleted" material. Some might go into SpecET. Some might go into a companion, referenced informative document about "Additional Useful Practices". Thus, those that want more can continue to drill deeper and find it. The point about "deleted" is that it disappears from this first, introductory level of "a dozen simple rules". Most of it should survive and be findable by drilling down sufficiently deeply, for those who want to do more ("Advanced Users").
This is a placeholder proposal for a future lightweight SpecGL. That would be one of a trio of documents about how to write clearer, more precise, more testable specifications. The other two are @@SpecLite -- Templates@@, and @@SpecLite -- Examples & Techniques@@. Though SpecGL is the proper normative set of rules for the topics of SpecLite, and the intended entry point to the SpecLite QAF component, the trio should be crafted in such a way that one could start with any one and easily find the related parts of the others.
One other thought. We are starting with prototype implementation (templates), and proceeding to defining a rule set (this). In the first-cut rule set below, it looks like it would probably be straightforward to group the rules into 3-4 overall principles. These could be developed as modules (in the SpecGL sense).
Final note. I have failed to get down to 10 or 12, which I guessed at the outset would be the count/result. (First attempt preserves 15 CPs). We could probably trim and consolidate more. (This is where the fun starts!).
Guideline 1. Define Scope. ["Define & illustrate scope?"] |
||
| Nbr | Checkpoint | Comments |
|---|---|---|
| 1.1 | Define and illustrate scope. |
Deleted 1.2 and 1.3 (both P2). 1.2 could be rolled into ET, or 1.2/1.3 into separate informative "Add'l. Recommended Practices", or ... |
Guideline 8. Document the conformance policy. [move it up above all the DoV] |
||
| Nbr | Checkpoint | Comments |
| 8.1 | Include a conformance section. |
Bingo, numero-uno! This is old-8.4. |
| 8.2 | Clearly explain all conformance concepts used, including any unusual conformance designations. |
Old-8.5 is rolled into here. Old-8.1 and old-8.3 are deleted. |
Guideline 7. Clearly identify conformance requirements. |
||
| Nbr | Checkpoint | Comments |
| 7.2 | Clearly define what is normative and how it is distinguished from informative content. |
old-7.1 ("conf. keywords") is rolled into here (altho' I don't feel strongly about combined vs. separate) and made more neutral about RFC2119 vs. other well-defined styles of normative language. Part of this new CP is high-level distinguishing of norm./inform. (like old-7.2), and part of it is the specific language used in individual testable statements. |
Guideline 2. Identify what needs to conform and how. [the old DoV start here -- "ways in which conforming impls. may differ". More formal treatment of DoV as such can be background reference, findable with some drilling down past the practical introductory level.] |
||
| Nbr | Checkpoint | Comments |
| 2.1 | Identify the conformance targets and define their conformance requirements. |
Rolled 2.2 into here. Deleted 2.3 and 2.4. 2.3 (Spec Categories -- forget it. 2.4 (DoV interrelationship) -- maybe relegate to SpecET (for *all* DoV). |
Guideline 3. Address the use of profiles, modules and levels to divide the technology. |
||
| Nbr | Checkpoint | Comments |
| 3.1 | Indicate if the specification uses profiles to subdivide the technology, and describe the details. |
Old 3.2 eliminated, old 3.3 ("rules for profiles") might get migrated to SpecET and/or template. |
| 3.2 | Indicate if the specification uses modules to subdivide the technology, and describe the details. |
Replaces old 3.4. Relies on template, and on SpecET stuff. |
| 3.3 | Indicate if the specification uses levels to subdivide the technology, and describe the details. |
New. Relies on template, and on SpecET stuff.
Ed note. In theory we could roll P/M/L together. But we found in the past that it's easier to talk about 'em if we keep 'em separate. |
Guideline 4. Identify the relation between deprecated features and conformance. |
||
| Nbr | Checkpoint | Comments |
| 4.1 | Identify all deprecated features and for each one define its implications on conformance for each CoP. [tbd ... better terminology for high level rule statement.] |
Rolled 4.2 into here. Deleted 4.3 and 4.4 (DoV inter-relationship, and deprecation rationale). Deleted 4.5 (examples how to avoid) -- maybe address it in SpecET. 4.6 (obsolete features, P3) could go away, or be dealt with in template or SpecET. |
Guideline 5. Define discretionary items. |
||
| Nbr | Checkpoint | Comments |
| 5.1 | Identify all discretionary items and discuss their conditions and constraints. |
Rolls 5.2, 5.3, 5.4 into 5.1. Their details would either be in ET & template, or in "Add'l Useful Practices", or both. As with all the other "DoV-inter-relationship" CPs, 5.5 gets deleted. They should definitely be mentioned in Techniques, and there should an associated QT-type document that describes & illustrates the importance of the topic (for advanced users). |
| As with all the other "DoV-inter-relationship" CPs, 5.5 gets deleted. The topic should definitely be mentioned somewhere like Techniques, and there should an associated QT-type document that describes & illustrates the importance of the topic (for advanced users). | ||
Guideline 6. Allow extensions or not. |
||
| Nbr | Checkpoint | Comments |
| 6.1 | Declare whether or not the specification is extensible. |
Extensibility, we agree, is one that needs the most careful handling. I split off the declaration by itself here. |
| 6.2 | Define the scope and constraints of any allowable extensions. |
Here, roll together the details of old-6.1, and maybe some of old-6.2 ("prevent...contradict") and maybe some of old-6.5 ("mitigate..."). As usual, the details will migrate down to [...ET, templates, "Add'l Useful..."] |
| 6.3 | Define a uniform mechanism to create an extension. |
TP2004 and other feedback, plus "Web Arch", suggests that this is an important one. |
| Delete 6.4 and 6.6. (I.e., downgrade them to supporting materials.) | ||
Guideline 9. Explain how to make conformance claims. |
||
| Nbr | Checkpoint | Comments |
| 9.1 | Provide specific wording for conformance claims. |
Old-9.5 ("require a completed ICS") could be rolled into here as a last, optional bullet. Old-9.4 ("provide ICS pro-forma") could be add'l suggested (extra credit) here, or advanced topic, or etc. Old-9.2 and old-9.3 are deleted. |
Guideline 10. Provide test assertions. |
||
| Nbr | Checkpoint | Comments |
[All gone.] |
Old-10.1 ("provide TAs") and 10.2 ("provide TA-to-spec mapping") either get deleted, or morphed into techniques for something like, "Subject the spec. to rigorous quality review." | |