Webapps/SpecEditing

From W3C Wiki

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

With respect to bug processing, expectations for Editors include:

  • When a bug is closed with a fix, include in the bug a link to the fix's patch/changeset

TR Publication Rules

The W3C's Publication Rules (aka PubRules) defines the requirements for documents published as a W3C Technical Report (TR). When a document meets all of the publication requirements it is said to be "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 starts a 1-week Call for Consensus (CfC) to publish the document. If the document is a plain WD there is no need for a CfC but some type of heads up (such as PublicServiceAnnoucement aka PSA) should be sent to public-webapps.
  • 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/).
  • 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).
  • Editor prepares the document for publication per the PubRules by doing the following.
    • 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 Validators. Note some 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.
  1. HTML Validator
  2. CSS Validator
  3. Link Checker
  4. Web IDL Validator - Run this if the document includes WebIDL and fix reported 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 will 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.
  • There are publication blackout dates at the end of the year, during the TPAC meeting week and during AC meeting weeks.

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. The minimum requirements for tracking each comment is:

  1. A public record of all comments (URL of comment, commenter's name, comment date, etc.)
  2. A public record of the group's response to the commenter
  3. 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):

Retrieved from "https://www.w3.org/wiki/index.php?title=Webapps/SpecEditing&oldid=79825"