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 |