W3C Technical Reports | Guide

How to Write a W3C Technical Report (historical)

NOTE: For operational process purposes, this document has been superceded by Publication Rules. It's kinda disorganized, but it's still got some valuable bits. I'd like to move the various bits (on references, on copyright/trademark) to smaller, public documents, and share them with the spec-prod community. --Dan, 4Jan2001

Most of this document is now in the W3C Manual of Style in development on spec-prod. --SusanL, 17 November 2001

This is some collected wisdom on how to write a W3C Technical report (e.g., Note, Working Draft, Recommendation).

See also:

Contents


Publishing Process

To have a document published on the Technical Reports page:

  1. The editor prepares the document according to W3C Technical Reports Style, ensures that it conforms to document validity requirements, and sends a request for publication to the W3C Team contact.
  2. The W3C Team contact
    1. obtains approval from the W3C Director to publish the document.
    2. coordinates between the editor the W3C Communications Team to prepare the release.
      (W3C Team: see also: internal process)
  3. When the W3C Communications Team is satisfied that all constraints in this document are met they release (and optionally announce) the document.

Roles

Refer also to the section on editors, authors, and contributors.

Editor
Editors are responsible for reflecting the proposals and consensus of the Working Group within a document. They must ensure that a document conforms to W3C publication styles and conventions. Editors make publication requests to the Director. They must agree to W3C's intellectual property policies. Editors are assigned by the Chair, as described in the W3C Process Document.
Author
Authors are Working Group participants who make substantial contributions to a document by writing proposals that serve as the basis for part of a the document. The Chair decides whether a person may be listed as an author based on the substance and quality of the person's contributions, the consistency of participation in Working Group meetings and the document's creation, the willingness to take action items and the person's actual written output.
Contributor
Contributors are those dedicated Working Group participants who provide the ideas, comments, feedback and implementation experience that improve the significance and quality of a document. The Chair decides whether a person may be listed as a contributor based on consistency of active participation in meetings and on the mailing list, and contributions towards resolving issues and reviewing documents.
W3C Team Contact
W3C designates a Team contact to participate in every Working Group or Interest Group (the contact is named in the charter) and to track every Submission request. The Team contact serves as liaison between a Group or Submitters and other groups and people within W3C, including the Director. When a Group Chair knows their Team contact will be away for several days or when a document will be published, they should arrange, with the Team contact, to find an alternate Team representative. The domain leader can serve as backup contact in extreme cases.
W3C Director
The role of W3C Director is played by Tim Berners-Lee and the W3C Team, especially the Team contact and W3C Domain Leader (@@link?). They are responsible for architectural consistency across W3C specifications, as process issues like seeing that a working group meets and stays within its charter, etc. (W3C Team: see also: internal process)
W3C Communications Team
The Communications Team has primary operational responsibility for the W3C Technical Reports archive, as well as communication with the membership and the press. We enforce consistency in the interest of communications efficiency.

Request For Publication

The process begins with a request ā la:

To: Team-contact@w3.org
Cc: W3C Communications Team <w3t-comm@w3.org>
        Tim Bray  <tbray@textuality.com> 
     Dave Hollander  <dmh@corp.hp.com> 
     Andrew Layman  <andrewl@microsoft.com>
Subject: Please Publish xml-names

Team contact's name,

Please consider the following publication request.
Let me know if there are any delays or you need
me to fix anything. Please don't change anything
without telling me.

Title: Name Spaces in XML
Short Name: xml-names
Status: Note
Date: 19-January-1998
Editors: 
     Tim Bray (Textuality and Netscape) <tbray@textuality.com> 
     Dave Hollander (Hewlett-Packard Company) <dmh@corp.hp.com> 
     Andrew Layman (Microsoft) <andrewl@microsoft.com> 

Status of this document

This document is a NOTE made available by the W3
Consortium for discussion only. This indicates no
endorsement of its content, nor that the Consortium has,
is, or will be allocating any resources to the issues
addressed by the NOTE.

This work is part of the W3C XML Activity.

The XML WG solicits comments from W3C member
companies and W3C working groups that use the
namespace mechanism described in this Note. In
particular, comments on open issues are very welcome,
and should be sent to the editors.

By this email I agree to W3C's intellectual property
right statement as described in [1]
[1] http://www.w3.org/Consortium/Legal/ipr-notice.html#Copyright

If the document updates/obsoletes other W3C Technical Reports, be sure to note them (by title, date, and address) in your request. In particular, include the address of the previous version of the document, if there is one.

@@open issue: who sets the date? The editor? The communications team? What if the document references itself? What about dates in the alternative versions, such as generated postscript?

Your Team contact should keep you up to date on the progress of your request. Within a few days or a week (@@more? less?) they should send email giving either

In your request, please indicate the extent to which the W3C Team is requested/allowed to edit your document; for example

Feel free to edit the title page to suit W3C style, but if the other content needs changing, I'll do it. Please send me diffs of any changes you make.

or

If one byte needs to be changed, stop and contact me. The HTML is machine-generated, and if editing it directly is counterproductive.

Also, include any relevant information about the urgency of your request, such as external commitments, dependencies, etc.

Publication Approval

Working Group actions

@@Not sure what this section is about. - Ian 4 April 1999@@

If a working group makes a document, it should be the chair who takes the action as representing the group.

For Working Drafts, there is no requirement for review of a document outside the Working Group, and groups are encouraged to make working drafts frequently.

However, for Proposed Recommendations, there must be a review within the W3C community (checklist next).

@@open issue: coordination between the chair and the editor (or worse: the chairs and editors) is tricky. Who actually sends the request?

Announcing the Release

The W3C Communications Team sends out the call for review/announcement: post to www-talk, comp.infosystem.www.announce, and that sort of thing.

A press release may accompany either a first public Working Draft or a Recommendation.

An announcement must be sent to chairs for a document entering last call (checklist next).

(@@notes on press releases?)

Document Identification

Semantics of "this version" and "latest version" URIs

Each technical report is a stable published document that has a document identifier often called the "this version" URI. W3C will not change the bytes of a stable published document; old stable published documents will remain available at the W3C site. Dates are used to ensure unique document identifiers.

Each stable published document in a series has a URI that, when dereferenced, returns the latest document in the series, called the "latest version". A stable published document URI must not be automatically redirected to the latest version.

Additional semantics for a latest version URI:

Syntax of "this version" and "latest version" URIs

Use this syntax for document identifiers:

      http://www.w3.org/TR/YYYY/STATUS-shortname-YYYYMMDD

where:

All YYYY and MM parts must agree.

Use this syntax for "latest version" URIs:

     http://www.w3.org/TR/shortname

This URI must be updated (e.g., an updated symlink) each time a document in the series is published to designate the latest stable published document in the series.

Access privileges for documents in "/TR/YYYY" space will be controlled by ACLs. @@Note: ACL control is not yet available as of 18 August 1999.@@

References to W3C Documents

Unless intentionally referring to the latest document in a series, people should always refer to specific documents (by using the "this version" URI). References should not include any trailing ".html" or other suffix since this is note part of the document identifier.

Document Status

The document status section describes the document status and publication context on the publication date. Since the document status section does not change over time, it must be expressed in terms that will be valid over time (e.g., avoid the word "new").

The status section should indicate the anticipated stability of the document (while recognizing that the future is unknown).

W3C will not make changes to a stable published document (through style, images, or other means) to indicate that is no longer the latest version. Readers are responsible for discovering the latest status information (e.g., by following the latest version link, reviewing the status page associated with the document series, or visiting the W3C Technical Reports page).

What to include in the Status Section

Each W3C Technical Report must have a section entitled "Status of This Document" that describes the document's status on the date of publication (checklist next). The status section is to be regarded as a label on the document authored by the W3C Team, not the author of the document.

The status section must include the following information:

In most cases, the document should also include an email address for comments, errata reports, etc. Documents in review (last call, Proposed Recommendation) must include an address specifically for Team-only review comments. When an email address is included, indicate whether people who send comments will receive responses (replies to Members? AC Reps only? to the general public?).

The status section must also include both of the following (in this order):

  1. A customized paragraph that has not been copied from another document. This section should include the release date of the document.
  2. A boilerplate paragraph (from the process document). See:

The custom paragraph is very important as it actually contains information! Don't paste it in from somewhere else. Write it specially. Put in it what you would reply to a member or colleague who asked you such things as:

For pre-release drafts, the status section should clearly state any limits on redistribution, such as "Member confidential."

So that readers will understand the purpose of the status section, authors should use the following boilerplate text in the document status section and link to a section entitled About W3C docs:

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The [latest status] of this document series is maintained at the W3C.

The [latest status] is a link to the status page.

Here is a sample paragraph for a public Working Draft:

This is a public W3C Working Draft for review by W3C members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of current public W3C Working Drafts can be found at http://www.w3.org/TR.

Here is the sample status section of a W3C Note, indicating the level of endorsement within W3C:

This document is a NOTE made available by the W3C for discussion only. Publication of this Note by W3C does not imply endorsement by W3C, including the Team and Membership.

If W3C has no resources allocated to a Note, the status section should include a statement such as:

No W3C resources were, are, or will be allocated to the issues addressed by this W3C Note.

If the document was not prepared or authored by the Team, the status section should include a statement such as:

The W3C Team has had no editorial control over the preparation of this W3C Note.

The "About W3C Documents" Section

@@In development@@

@@Jean-Francois suggests parameterizing this text for each document: show your own "latest version" URI in the text below.@@

Include the following text in a section entitled "About W3C Documents" at the end of a document:

To promote confidence and stability, W3C has instituted the following publication policies:
  1. Each technical report is a stable published document that has a unique identifier (URI).
  2. Each stable published document will always be available, unchanged, at that URI. Retrieving (e.g., by bookmarking) the resource at that URI will always return the same content.
  3. A specific revision of a document is generally one of a series of related documents (e.g., from Working Draft to Recommendation). Each series has a unique identifier (URI) that when followed, will return the latest stable published document available in the series.
  4. Each document includes a "Status" section that describes the document's publication context on the date of publication. Note that since W3C does not change stable published documents, the status section of a published document cannot be changed, even if the document becomes obsolete at a later date.
  5. Each document in the series includes links to up-to-date status information for the series.

Status Page

@@In development@@. A status page includes information about the document series revision history (including, e.g., that a specific version has been superseded). Refer, for example, to the RDF Schema Proposed Recommendation Status page or the WebData NOTE.

On the status page:

W3C Technical Reports Structure

The editor is responsible for preparing the document according to W3C document structure and style conventions. There is no central W3C service to do this, so if you will need copy editing help, you will have to negotiate that in advance.

Each W3C technical report consists of the following sections, in this order:

The Technical Report template illustrates exactly how the document head should be constructed. Make sure that the first part of your technical report is structurally identical to that of the template.

To use the template to build a document:

See also the original sample Recommendation from Håkon.

You should change the content according to the specification you are publishing and perhaps some of the head information (e.g., if there's no previous version). However, you should respect the template structure as much as possible.

See also the requirements for compound documents.

Document Head

The document head consists of:

Document Title

The name of your document in the document head and on the TR page will read as follows. Optional elements are in brackets.

Title [(ACRONYM)] ["Level" n] ["Specification"][: Subtitle] ["Module"] [(nth "Edition")] ["Version" Version_Number]

DD Month Year, Editors.

Alternative Formats

All Technical Reports are published in HTML. You may optionally prepare plain text, postscript, XML PDF, etc. format versions of the draft. (See multiformat tools, notes on spec management and production). These renditions should reference the HTML rendition as authoritative.

The HTML format should reference the others; for example:

This version:
http://www.w3.org/TR/1998/xml-names-19980119
(text, XML, PostScript, PDF)

where "XML" is a link that refers, for example, to http://www.w3.org/TR/1998/xml-names-19980119.xml

Authors, Editors, and Contributors

The Chair decides who qualifies as editor, author, and contributor for a document. Decisions must be based on the role descriptions in this document and must fairly reflect the individual's contributions. The Chair should set expectations early so that Working Group participants understand roles and associated credit and responsibilities. One example of determining roles is provided by the XML Signature Working Group Chair.

Editors and authors are listed in the head of the document. Contributors are listed in the acknowledgments section. However, if the list of authors is very long (e.g., the entire Working Group), the authors should be listed (and highlighted) in the acknowledgments section, linked from the head of the document.

Listing affiliations and email addresses is at the discretion of the editors. Note that for the purposes of document review, it is generally preferable to list a single email address and ensure that email sent to that addressed is archived.

Abstract

Each document must have an Abstract (a few paragraphs at most) that summarizes what the document is about (checklist next).

Obsolete Documents

@@Under construction 25 October 2000@@

When a document becomes obsolete, abandoned, or otherwise is to be retired, the following is recommended: end the document series by requesting publication of a Note whose status section explains the document's destiny. Be careful not to break links in this version!

Examples

Errata

@@See also Proposal to chairs based on Martin comments. This proposal has not yet been reviewed.

All Recommendations have errors in them and they should all link to an errata page that evolves over time. Since the errata page changes over time but a specific version of a Recommendation does not, the errata page should be outside of the /TR hierarchy. There is an expectation that documents in the "TR zone" will not evolve over time. Errata pages should be located, for example, in the portion of the Web space dedicated to the relevant Working Group or Activity.

The errata page must clearly indicate:

For example (shown here without links):

This document:
http://www.w3.org/Style/css2-updates/REC-CSS2-19980512-errata
Last revised:
$Date: 2018/01/25 15:57:29 $
This document records known errors in the document:
http://www.w3.org/TR/1998/REC-CSS2-19980512
The latest version of the CSS 2 Recommendation:
http://www.w3.org/TR/REC-CSS2

When a new revision of the source document is published, the accumulated errata should be folded into the new revision as a list of changes. The associated errata page should be "wiped clean" and the URI updated to designate the new source document revision.

Errata pages should indicate the severity of each entry:

References

If there's an institutionalized identifier (URI) for a document, cite the most specific identifier (along with title and date). For example:

"<a href="http://www.w3.org/TR/1999/REC-html401-19991224">
HTML 4.0 Recommendation</a>", 
     D. Raggett, A. Le Hors, and I. Jacobs, eds., 
     17 December 1997, revised 24 April 1998, revised 24 December 1999. 
  This version of the HTML 4.01 Recommendation is
       http://www.w3.org/TR/1998/REC-html40-19980424.
  The <a href="http://www.w3.org/TR/html4">latest version
            of HTML 4</a> is available at
       http://www.w3.org/TR/html4.

Please use reference titles, not addresses, as link text. Refer to email from Dan on reference titles Refer also to "in your face URLs: please don't.

@@Dan proposes: No links point outside the document except on the title page and in the references section.

@@Ian proposes instead 16 December 1999:

When linking from the middle of the document to an external resource:

  1. Ensure that the link text, title, and context indicate you are leaving the document, and
  2. After the link, link to the reference in the references section, and indicate section, page, or whatever is useful for those who don't use the link (e.g,. when printed).

Thus, for example: ... as is done for the 'page' property of CSS2 ([CSS2], section 13.3.2.).

@@Ian Proposes:

For further discussion, see:

Mar 1999: @@Dan adds:

There are two very distinct kinds of resources on the Web

published documents
these are historical artifacts; matters of record. They are 'released' in some way that cannot be repudiated (e.g., announced in email messages that can't be recalled, distributed in thousands of hardcopies that can't be recalled, put on an ftp/http server with license to freely redistribute and republish, etc.)

For example, even if W3C ceases to operate tomorrow, it's reasonable to expect that the address: http://www.w3.org/TR/1998/REC-html40-19980424/ will be served in perpetuity, given its value to the community.

You can successfully dereference that address without being connected to the net, if you have it in cache or on CD-ROM or some such.

living documents
which might be better known as "services." In order to successfully dereference the address of a living document, you have to be online and contact the information provider synchronously (or close to synchronous, i.e., within some expiry period).

For example, if W3C folds, it becomes impossible to dereference the "latest version" address http://www.w3.org/TR/1998/REC-html40 because its semantics are "ask the W3C Director what he considers the latest version of HTML 4.0 to be." (this address will probably be serviced anyway, but it must be serviced using the 203 Non-Authoritative Information HTTP response code [draft6, November 18, 1998] )

Citing a living document is an expression of trust, while citing a published document is a simple reference to historical fact.

Implicit in "we always refer to the most up-to-date form of ISO 10646" is "we trust that ISO will maintain the 10646 spec in perpetuity and with sound technical judgement." The authority to make such liaison statements is held by the W3C Director. In the normal course of events, the Director exercised this authority in the following ways:

Based on notes from 6 April Chairs meeting: When referring to characters (in Unicode/10646), consider whether you are referring just to a set of integers (whatever characters those integers refer to) or whether you are referring to a specific set of characters - a semantic group - (e.g., three or four that comprise "white space") that will not change even if similar characters are added to Unicode. In the former case, the reference may be to a living repositor; in the latter, refer to a dated version of the specification.

Large documents

Large single files that may be easy to print may not be easy to download. For large documents, we strongly encourage editors to:

  1. Divide the document logically, storing chapters in separate files. Refer to the section on compound documents.
  2. Offer an archived version (zip, tgz) of the separate files.
  3. Offer a single, printable version of the spec. This format may be compressed if too large.

Compound Documents

(@@notes on compound documents: figures, graphics formats, etc.?)

Translations

As of July 1999, W3C does not have offical translations of its technical reports. However, we do encourage people to translate the technical reports and help track translators and translations.

W3C Technical Reports Style

Here are the steps you should go through to ensue that your markup is according to W3C Technical Reports Style:

Also, Technical Reports should follow the Styleguide for Online Hypertext.

Bear in mind that our reports are used as world-class primary reference material. Readability across a wide variety of browsers and platforms is far more important than using jazzy features. At some point, what we write becomes History.

Document validation

Note. It is not the role of the Team Contact or of the W3C Communications or Web Teams to ensure that documents are valid; it is the Editor's responsibility. The Communications and Web Teams are prepared to make minor changes to documents to make them valid, but the Editor should ensure validity before requesting publication. The W3C makes available validation services to assist Editors.

Please follow these steps to ensure that your documents are valid once in TR space:

Copyright and Intellectual Property Rights

The W3C membership contract says that products of W3C working groups are jointly owned by the membership and the host institutions.

Anyone who requests publication of a tech report who is not covered by the contract must execute the copyright release form.

@@Information about republishing W3C tech reports in other formats to be provided by Reagle (2 March 2000)@@.

Copyright notices in Working Drafts, Proposed Recs, and Recs

Each of these documents must include W3C copyright information within their status. The HTML for this is

<p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#Copyright"> Copyright</a> &copy;2001 <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>&reg;</sup> (<a href="http://www.lcs.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="http://www.inria.fr/"><abbr lang="fr" title="Institut National de Recherche en Informatique et Automatique">INRIA</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice-20000612#W3C_Trademarks">trademark</a>, <a href="http://www.w3.org/Consortium/Legal/copyright-documents-19990405">document use</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-software-19980720">software licensing</a> rules apply.</p>

Archives of files (particularly source code) should include an instance of following short copyright declaration template within the source code itself and also have copies of the complete document and software notices and licenses included. Note that the this statement uses dated URIs that identify static documents.

From Joseph Reagle's message to chairs about date ranges:

... I would recommend that on a dated instance of a specification always use the specific year of that dated version

One should not update the copyright date of a dynamic page with the present year such that the first publication date is removed:

  1. If a document changes frequently, it makes sense to use a range, starting from the first date of publication.
  2. If they don't change, they should retain the original date.

Copyright notices in NOTES

Notes (e.g., for documents that are part of a Submission package) may contain copyright statements from Member organizations. However, as illustrated by the P3P/CACM NOTE, a comment should be added stating that distribution of the NOTE is governed by the W3C intellectual property terms. The HTML for this is:

Distribution policies are governed by the W3C intellectual property <A
HREF="http://www.w3.org/Consortium/Legal/ipr-notice.html#Copyright">terms</A>.

Ian Jacobs (ij@w3.org), Joseph Reagle:IPR (reagle@w3.org)
Håkon Lie
(howcome@w3.org) for Tim Berners-Lee
Created 21 Jan 1998
last revised $Date: 2018/01/25 15:57:29 $ by $Author: plehegar $ add