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:
@@@@ add to that: I propose that, where pubRules after section 3.2 which says that a namespace must have a we also agree that: - This also applies to any other URI being institutionalized by the spec eg HTTP extension etc - it must dereference at least to an HTML placeholder documentl - where the URI is mentioned there be an <A HREF... > around the URI so folks can follow it. - after XML schema goes to PR (and ideal;ly immediately) for every namsepace there must be a schema. In the future, all XML documents published on the W3C website will be grounded in the web: all images must exist; similarly, XML documents must use namespaces which must dereference to a schema. For a document at a given level, the set of documents involved in this process must be at the same or higher level of standardization, subject to the flexibility we introduce with executive discretion to allow allow progress despite mutual normative references. progress despite mutual normative references. - Tim@@@ @@
To have a document published on the Technical Reports page:
Refer also to the section on editors, authors, and contributors.
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.
@@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?
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?)
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:
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.@@
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.
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).
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):
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.
@@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:
- Each technical report is a stable published document that has a unique identifier (URI).
- 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.
- 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.
- 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.
- Each document in the series includes links to up-to-date status information for the series.
@@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:
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.
The document head consists of:
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]
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:
where "XML" is a link that refers, for example, to http://www.w3.org/TR/1998/xml-names-19980119.xml
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.
Each document must have an Abstract (a few paragraphs at most) that summarizes what the document is about (checklist next).
@@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!
@@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):
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:
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:
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
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.
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 single files that may be easy to print may not be easy to download. For large documents, we strongly encourage editors to:
(@@notes on compound documents: figures, graphics formats, etc.?)
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.
Here are the steps you should go through to ensue that your markup is according to W3C Technical Reports Style:
<LINK rel="stylesheet" type="text/css" media="screen"
href="http://www.w3.org/StyleSheets/TR/W3C-xxx.css">
The "xxx" should be replaced with "NOTE", "WD", "PR", or "REC". See the sample Recommendation for an example of how to do this.
Do not copy the style sheet into a local copy for the version available on the Web. You may create a local snapshot of the style sheets for offline viewing.
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.
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:
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)@@.
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> ©2001 <a
href="http://www.w3.org/"><abbr title="World Wide Web
Consortium">W3C</abbr></a><sup>®</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:
- If a document changes frequently, it makes sense to use a range, starting from the first date of publication.
- If they don't change, they should retain the original date.
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>.