SpecProd/Restyle/Content

From W3C Wiki

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