SpecProd/Restyle/Content
Common Spec Content
Suggested items are newly proposed.
Example
Here's a [sample restyle] that attempts to incorporate all of the data listed here, following inspiration from [Karl's message]. (The goal of this example was to explore what's possible.)
Data
This information is short and fairly standard: it needs a consistent location across W3C documents and doesn't involve customized prose.
Item | Required? | Primary Audience | Notes |
---|---|---|---|
W3C | all | all | Branding |
WG/TF | all | potential participants | Associated WG or Task Force |
Title | all | all | no comment |
Pub date | all | all | Indication of out-of-date-ness / recency of change |
Status | all | all | ED/WD/LC/CR/PR/REC/NOTE/etc. |
Status disclaimer | all | new to reading W3C specs | Warn people the document is unstable, etc. |
Copyright | all | lawyers | |
Patent Policy | some | laywers, implementers | implementers would care whether the spec is royalty-free |
Disclosures | some | lawyers | |
Errata | REC | implementers, reviewers | Only if there's errata |
Issues list | all? | reviewers | |
FAQ link | suggested | ||
At-risk list | LC/CR | W3C | |
Discussion fora / Feedback | all | reviewers | Mailing list, IRC, wiki, bugtracker, etc. |
Editor's draft | most | reviewers, implementers | |
Repository | most | reviewers, implementers | |
This version | all | reviewers, implementers | |
Previous version(s) | all | reviewers | |
Commits | some | reviewers | |
Test suite link | CR/REC | implementers, contributors | sometimes also pre-CR |
Implementation report | some | implementers, developers | |
Editors | all | participants | Tells people who to talk to and who can fix issues |
Translations | some | non-English speakers | |
Other formats | some | all | Links to other formats suitable for offline/printing; particularly useful for multipage specs |
Explainer or use cases link | some | implementers & developers | explanation of design choices, scope of feature, example code, etc. |
Prose
Meta-sections that are common to different specs.
Item | Required? | Primary Audience | Notes |
---|---|---|---|
Abstract / 2-sentence summary | all | all | We recommend compressing the abstract into a 2-sentence summary suitable for search results and other listings |
Illustrative example | suggested | all | to illustrate the abstract |
TOC | all | all | |
Overview | optional | all | A prose version of the TOC |
Introduction | optional | all | Introduces key concepts and sets context for understanding the spec |
Background | optional | ? | Gives Motivation/Historical Context for spec |
Use Cases and Requirements | required | reviewers and Director of W3C | Explain what problems trying to solve. Explicitly required by W3C Director to progress specification to CR. |
Scope | optional | editors/WG | |
Transition Criteria | some | participants | CR exit criteria. Suggest expanding to all other specs to explain exit criteria of other stages. N/A to REC / NOTE |
References | all | implementers | |
Conformance | some | implementers | |
Security & Privacy | some | all | Considerations for security and privacy |
Changes | some | reviewers | to list substantive changes |
Index/Glossary | optional | all | |
Acknowledgements | all | acknowledged |