SpecProd/Restyle/Content

From W3C Wiki
Jump to: navigation, search

Common Spec Content

Suggested items are newly proposed.

Example

Here's a [sample restyle] that attempts to incorporate all of the data listed here.

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
Previous version(s) all reviewers
Test suite Link CR/REC implementers, contributors sometimes also pre-CR
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

Prose

Meta-sections that are common to different specs.

Item Required? Primary Audience Notes
Abstract / 2-sentence summary 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
Index/Glossary optional all
Acknowledgements all acknowledged