Webapps/SpecEditing

From W3C Wiki
< Webapps
Revision as of 13:33, 19 June 2013 by Abarsto (Talk | contribs)

Jump to: navigation, search

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 and responsibilities including:

  • Making sure their specification(s) reflect consensus of all commenters, not just WG members (see WebApps' Consensus WorkMode and WebApps' Editor WorkMode for more information)
  • Making sure someone in 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 (see Last Call Comment Tracking below)
  • 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 Report (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 and WebApps

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 by doing the following.
    • Note for ReSpec users: before doing any validation, a static version of the document must be created and the static version should be used with the validators. One way to create the static document is to: load the document in the Chrome browser; simultaneously press the Ctrl+Alt+Shift+S keys; select "Save as HTML (Source)" and save the document (ReSpec has its own static output generator and it must be used).
    • Run the PubRules Checker
    • Check the PubRules Filter requirements and address all of the requirements for the specific publication type (e.g. FPWD, WD, LCWD, CR, etc.)
    • The document must pass at least the following Validations but 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.
    • If the document includes WebIDL, check the IDL with the online Web IDL validation tool and fix all errors
    • Make sure the Status of This Document section includes the subject tag prefix to be used for comments (e.g. [short-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:

Last Call Comment Tracking

The WG is responsible for replying to all spec comments. Additionally, after a spec is published as a Last Call Working Draft, the spec's Editor (or some other member(s) of the group) is required to track the LCWD comments. Tracking LCWD comments means that for each comment, there must be a public record of the group's response and a public record from the commenter that indicates whether or not the commenter is satisfied with the group's response.

There are several ways to track LCWD comments and there is no firm requirement on the exact mechanism used. Here are some different mechanisms with links to some examples:

Although it is not a firm requirement, Editors are encouraged to include a link to the LC comment tracking in the Status section of the LCWD publication.

Miscellaneous Resources

Related resources (some may be a bit outdated):