Difference between revisions of "Webapps/SpecEditing"

From W3C Wiki
Jump to: navigation, search
(Added link to Anne's This document explains basic guidelines for writing a specification for the web platform.)
(Tools for Authoring W3C Specifications)
Line 63: Line 63:
Other tools (not included in the list above):
Other tools (not included in the list above):
* [http://wiki.whatwg.org/wiki/Anolis Anolis] - used by at least CORS and DOM4
* [http://wiki.whatwg.org/wiki/Anolis Anolis] - used by CORS, DOM, XMLHttpRequest, Progress Events, From-Origin.
== Miscellaneous Resources ==
== Miscellaneous Resources ==

Revision as of 13:01, 23 May 2012

This document contains information and links that may be useful for Editors of WebApps' specs, including information about publishing a document as a W3C Technical Report, often called TR (and the document is said to be published in /TR/).

This document is a WorkInProgress and as such is subject to change. Members of the WebApps Working Group as well as the W3C community are encouraged to update and maintain this document!

Spec Editor Roles and Responsibilities

Besides the mechanics of specification authoring, WebApps' specification Editors also have other roles such as:

  • Making sure their specification(s) reflect consensus (see WebApps' Consensus WorkMode and WebApps' Editor WorkMode for more information)
  • Making sure the WG (not necessarily the Editor) responds to all comments submitted to their specification(s)
  • Tracking comments when a specification is in Last Call review. For more information on issue and bug tracking see WebApp's Issue and Tracking WorkMode wiki.
  • Making a specification Pubrules compliant before it can be published as a Technical Report (see below for details)
  • Assuring their specification(s) PubStatus data is accurate and current
  • Helping the Chairs and Team Contact find testing resources for the spec

TR Publication Rules

The W3C's Publication Rules aka Pubrules defines all of the requirements for documents that will be published as a W3C Technical Reports (TR). When a document meets all of the publication requirements it is referred to as "PubReady'".

  • PubRules - defines the publication requirements for documents based on the maturity level of the document. For example, the requirements for a Working Draft are different than the requirements for a Candidate Recommendation as indicated in the PubRules Filter. A document must meet every Pubrule requirement before it can be published in TR.

TR Publication Process

The TR publication process is formally defined in PubRules. Here is a brief summary of the general steps and tasks used by WebApps:

  • Some member of the group (e.g. Editor, Chair, etc.) proposes a document be published as a TR
  • Chair: start a 1-week Call for Consensus (CfC) to publish the document
  • If the document is a First Public Working Draft (FPWD):
    • Chair will submit a Transition Request to the group's Domain Lead and the Chairs list. The main reasons for this step are: to make sure the document is within the WG's scope; to notify other WGs about the group's intention to make the publication and to get agreement on the document's short-name (e.g. www.w3.org/TR/short-name/).
  • Editor: prepare the document for publication per the PubRules, starting with the PubRules Filter and addressing the requirements for the specific publication type (e.g. FPWD, WD, LCWD, CR, etc.)
    • The document must pass at least the following Validations including: HTML Validator, CSS Validator, Link Checker. Note the validators (especially the CSS validator) may report errors that are not errors. See the Validator Help Page for information about how to get help with the Validators and how to report Validator bugs/issues.
    • The Status of This Document section should include the subject tag prefix that should be used for comments (e.g. [spec-name] comment ...)
    • Notify team-webapps@w3.org when the document is PubReady
  • Chair or Team Contact: submit a Publication Request (aka PubReq) to the W3C's Publishing Team and Cc the document's primary Editor
    • The Publishing Team may ask the Editor to make some editorial changes
  • The document is published as a TR

Notes about publications:

  • TR publications are only made on Tuesdays and Thursdays
  • PubReqs must be sent at least two days before the requested publication date

Tools to Check Pubrules Compliance

The W3C maintains several online tools to check Pubrule compliance. For example, there is an HTML validation tool, CSS validation tool, link checker, etc.

A list of the online tools to check Pubrules compliance is provided in:

Tools for Authoring W3C Specifications

Editors in WebApps are free to choose their specification authoring tool(s). The most commonly used tool in WebApps is ReSpec but there is no requirement that it be used.

A list of specification authoring tools is provided in:

Other tools (not included in the list above):

  • Anolis - used by CORS, DOM, XMLHttpRequest, Progress Events, From-Origin.

Miscellaneous Resources

Related resources (some may be a bit outdated):