Skip to content

Latest commit

 

History

History
108 lines (68 loc) · 9.5 KB

SpecEditing.md

File metadata and controls

108 lines (68 loc) · 9.5 KB
Raw

This document contains information and links that may be useful for Editors of Web Platform 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 Web Platform 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, Web Platform specification Editors also have other roles and responsibilities including:

  • Making sure their specification(s) reflect consensus of all commenters, not just WG members (see Web Platform Consensus WorkMode and Web Platform 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 considered functionally complete and a request for wide review has been made (typically this done before a Candidate Recommendation is published).
  • 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
  • Use the W3C Software and Document license

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'".

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 the appropriate mail list(s).
  • 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).
  • Someone (Editor, Chair or staff contact) 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, 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 Chairs of staff contact 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 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 Web Platform are free to choose their specification authoring tool(s). The most commonly used tool in Web Platform is ReSpec but there is no requirement that it be used.

A list of specification authoring tools is provided in:

Comment Tracking

The WG is responsible for replying to all spec comments. Additionally, after a spec is published as a Candidate Recommendation, the spec's Editor (or some other member(s) of the group) is required to track the CR 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 CR 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 comment tracking in the Status section of the CR publication.

Miscellaneous Resources

Related resources (some may be a bit outdated):