This Guidebook is the collected wisdom of the W3C Group Chairs and other collaborators.

Introduction

One of the main accomplishments at W3C is to write specifications and create standards out of them. While the Working Groups at large are responsible for building consensus on the technical decisions, the editors have the heavy responsibility of transforming these decisions into actual specifications.

This page tries to gather resources that can help editors do their job: documentation, tools, tutorials, etc. If you know other resources that would benefit editors by being listed here, please inform the W3C Communication Team at w3t-comm@w3.org.

Where to start?

If you are a newly appointed editor in your Working Group, here is some advice that should be useful to get you started.

• Get an idea of the role of an editor at W3C
• Read the W3C Publication Rules (often referred as pubrules) and ask advice on the points that are unclear; if your document doesn't comply with these rules, it cannot be published as a W3C technical report.
• How to Organize a Recommendation Track Transition explains the process to get a document published as a technical report.
• The Pubrules Checker is a tool that can help you assess whether or not your document complies with pubrules.
• Level A conformance to the Web Content Accessibility Guidelines 1.0 is required for all W3C technical reports.
• All W3C editors are invited to join the publicly archived mailing list <spec-prod@w3.org> to share and discuss the techniques and tools used to produce W3C specifications.
• if you're using JigEdit to edit documents, the JigEdit Guide is a useful resource

Guidelines on W3C specifications editing

W3C has developed a set of resources giving advices and guidelines on editing W3C specifications in varous domains:

• The W3C Manual of Style is a collection of rules you're invited to follow to make your document clearer and adapted to the common style at W3C.
• Begun in 1992 and only a little out of date, the Style Guide for online hypertext by Tim Berners-Lee is a good start on writing for the Web; see also Jakob Nielsen's How Users Read on the Web
• The QA Framework: Specification Guidelines from the W3C Quality Assurance Activity are a work in progress that became a Candidate Recommendation in November 2003.
• The Team has guidelines for a style for group-internal drafts to avoid confusion with documents published on the TR page. Please also review the related Working Group Heartbeat Requirement of the W3C Process.

Bert Bos's essay on W3C's design principles and Tim Berners-Lee's essentials of a specification may also be a useful reading.

During the internal development of a specification, make sure to distinguish official drafts from internal ones using the style for Group-internal Drafts.

Grammars

W3C editors have developed several types of HTML and XML based grammars to make it easier to develop and maintain their specifications. We try to maintain a list of these grammars; XMLSpec is the most-often used incarnation of these grammars – Karl <karl@w3.org> plans to work on setting up a documentation for it, but you can see what e.g. Web Services Addressing 1.0 - Core looks like in XMLSpec and read a few introductory materials: Richard Ishida's guide, the DI Working Group introduction to it (Member-only), Why Use XMLSpec? (Member-only).

Some raw results of a survey [Member-only] done among editors at the end of 2002 can help you in your choices.

Authoring tools

To create XHTML documents, using Amaya - W3C Browser/Editor - is a good option to create valid markup, but there are other tools available.

When using XMLSpec, having a good XML editor can help; the following tools have proven useful for some editors:

• nXML-mode in emacs
• XMLSpy for which Altova offers a license to W3C Working Group participants that need it (Member-only)
• oXygen XML, for which Syncro Soft offers a license to W3C Working Group participants that need it (May 2005 license - Member-only)
• XMetal (see Richard Ishida's setup for editing XHTML with XMetal)

Tools

Here are tools that can prove to be useful when developing your specification.

• The Pubrules Checker provides a convenient interface to check the conformance of a document to pubrules.
• The Technical Reports shopping list and the Bibliography Extractor help building bibliographies based on other W3C Technical Reports; there is a similar mechansim for XMLSpec
• The TR references checker may help maintain your references list up to date
• The W3C Glossary is a repository of all the terms defined in W3C specifications (and more); a good source to find which terms have already been defined and where
• The on-line Spell Checker helps spot misspellings and typos; the W3C on-line Stylistic Checker helps find the most usual errors identified by the W3C Manual of Style
• different tools are available to produce a diff between 2 HTML versions of a document (contributions welcome in the relevant Wiki page)
• The MarkUp Validator can help you assess whether your documents are valid HTML, MathML or SVG.
• The CSS Validator tells you if your use of CSS is correct.
• The Link Checker catches all the broken links that may have popped up in your document.
• The Namespace checker finds potential namespaces URIs in the documents, and makes a few checks on them
• HTML Tidy, originally by Dave Raggett and now maintained at SourceForge.net, is a lint that cleans up but does not validate HTML and XHTML. With indent off, Tidy can sometimes shave 10% or more off file size.

Most of these tools can be quickly accessed using the so called ,tools interface: appending ,keyword to a www.w3.org URI triggers a certain tool on this URI; for instance, appending ,validate to this page's URI will send it to the HTML validator.