Tools

This is the W3C Manual of Style based on How to Write a W3C Technical Report (W3C
Member-only link). This manual is a guide containing best current
practice. No requirements for W3C publications are in this document.
All requirements for W3C publications are in W3C Publication
Rules [PUBRULES].

Helpful resources for editors and authors are kept on the
W3C Editors Home
Page [EDITORS].
Notes on document management are available [MANAGE]. When in doubt, ask for help on the
public mailing list spec-prod@w3.org [SPEC-PROD].

Please send
your comments to the public mailing list spec-prod@w3.org (archive).
If for any reason you do not
wish your contributions to be credited in Acknowledgments, please indicate this in your email.

Written for editors and authors of W3C technical reports, this
document assumes that the reader has mastered publishing on the W3C Web
site, and is familiar with the Style Guide for Online
Hypertext [STYLE-GUIDE]. It is a companion to the
REQUIREDTechnical Report Publication
Policy [PUBRULES],
called "pubrules" for short. Following the advice in this manual has
benefits:

Non-native English readers, native English readers, and translators
will find your text easy to read and implement.

All audiences can concentrate on ideas rather than the mechanics of
reading.

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 and is preserved on the Web
through the W3C Persistence
Policy [PERSISTENCE].

Make sure there are no broken links in your documents at the time
of publication. Some services on the Web may help you with this,
including the W3C Link Checker [CHECKLINK]. Append ",checklink" to a W3C
URI to invoke the link
checker.

Make sure your technical report validates in the W3C Markup
Validation Service [VALIDATE]. Append ",validate" to a W3C
URI to invoke the
validator.

Make sure your technical report validates in the W3C
CSS Validation
Service [CSSVALIDATE]. Append ",cssvalidate" to a
W3C URI to invoke the
CSS validator.

Make sure any examples in your document validate as well.

Note. It is the editor's responsibility to ensure
that documents are valid before requesting publication.

Follow the Character Model for the World Wide Web 1.0:
Fundamentals W3C work in progress [CHARMOD]. Does your specification define
protocols or format elements? If it does, define when conversion to
legal URI reference
characters takes place, and do so as late as possible.

When specifying characters, refer to The Unicode
Standard; see section 8 of the Character
Model for the World Wide Web 1.0: Fundamentals [CHARMOD]. The Unicode Consortium gives
guidelines for how to cite their standards; see [UNICODE]. Refer to individual characters in
any of three ways; see the email thread "Unicode character
names" [CHARNAMES]:

Although technical reports are written in U.S. English, examples and
wording should not rely on conventions and idioms used only in the
United States (e.g., "ZIP
code"). Use international examples (e.g.,
"postal code") wherever possible.

Make your specification more readable by adding markup to
distinguish common words from keywords in your language. Mark up every
occurrence. For example:

The title attribute of these elements
may be used to provide the full
or expanded form of the expression.

becomes:

The <code>title</code> attribute of these elements
may be used to provide the full
or expanded form of the expression.

A French translator would then know not to translate title
to titre.

First person pronouns ("I," "we") which are hard to translate should
not be used in the text of examples. See the email message
"Personal pronouns in specifications" [PRONOUNS]. Avoid "my" and "me" in examples
(e.g., use "userResource" and not
"myResource").

Specifications should not directly address the reader as well.
Translating second person singular pronouns is a hard task if the
language distinguishes between various forms like formal and informal
of "you," hence avoid "you."

Do not invent elements to replace natural language. For example, do
not use <must/> and a stylesheet to render MUST.
Other languages may need grammatical agreement with the sentence's
subject, e.g., in French, MUST will become
DOIT if the subject is singular, or
DOIVENT if it is plural. Use standard
markup instead.

5/6/03 to denote a date is ambiguous in the international context
(the example could mean 6 May or 5 June). Either spell out the month (6
May 2003) or use an ISO-8601-derived form (2003-05-06). XML Schema Part 2:
Datatypes ([SCHEMA-DATATYPES], sections 3.2.9
through 3.2.14.1) formally explains how to write dates in XML
documents.

Give each document an
Abstract (a few paragraphs at most) that summarizes what the
document is about. The Communications Team may use the Abstract as a
whole or in part to publicize your work. Write it for a non-technical
audience.

The "Status of This Document" section describes the document status
and publication context on the publication date. Pubrules
[PUBRULES] states the
requirements for the status section of each type of technical report
(e.g., use of customized and boilerplate text).

Since the status section does not change over time, express it in
terms that will be valid over time (e.g.,
avoid the word "new"). Indicate the anticipated stability of the
document while recognizing that the future is unknown. Readers are
responsible for discovering the latest status information (e.g., by following the latest version link, or visiting
the W3C technical reports index [TR].

The custom paragraph is very important as it actually contains
information! In it, you should explain where a part of the energy of
the group has been invested. The custom paragraph should help a reader
decide "I really should read this draft." This implies that you
shouldn't paste it in from somewhere else. It should be very specific
to this document.

TimBL expressed the goal of the custom paragraph this way, "Don't be
afraid of being honest about the relevant techno-political situation."
In the custom paragraph, make th case for why someone should read this
draft.

In the custom paragraph, include what you would reply to a Member or
colleague who asked you such things as:

Are we requesting that people implement this specification? If so,
where should experience reports be sent?

Are we requesting people do not implement the
specification until a later date? What sort of damage do we expect to
inflict on those who do by future changes to the document?

Does it reflect the consensus of a W3C Working Group? (Pay
attention to the authors and acknowledgments.)

Are there any changes expected?

Do we maintain a page of background information (e.g., the P3PFAQ [P3PFAQ])?

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

All Recommendations have errors in them. They 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, place the errata page
outside of the /TR hierarchy. There is an
expectation that documents in the "TR zone" will not evolve over time
[PERSISTENCE]. For example,
locate errata pages in the portion of the Web space dedicated to the
relevant Working Group or Activity.

All entries in a references section should be referred to in the
prose. If an entry is not referred to from the body of the document,
make it clear why it is in the References section.

If a reference is a W3C Recommendation track technical report that
has not reached Recommendation, state in the References section that it
is "work in progress."

It is helpful to include references to both persistent resources
and their latest version. Use titles for links. If there is an
institutionalized identifier (URI) for a document, cite the most
specific identifier. For example, usually you would link the title to
http://www.w3.org/TR/1999/REC-html401-19991224 rather than
to http://www.w3.org/TR/html4/. For more information on
using versioned and unversioned identifiers, refer to the
Character
Model for the World Wide Web 1.0: Fundamentals
([CHARMOD] section 8).

An entry in a references section takes this form:

Title, inside a (if available), inside
cite

Comma-delimited list of authors' names

If there are no authors, use editors instead if available.
Following the last family name, say "eds." or "Editors."

Publisher, followed by the date of publication in the form DD Month
YYYY

Reference titles are recommended, not the "URI-in-your-face" idiom, as link
text; see [REF-TITLES]. For
example, Do use: <cite><a
href="http://www.w3.org/TR/1999/REC-html401-19991224/">HTML 4.01
Specification</a></cite>. Do not use:
<cite><a
href="http://www.w3.org/TR/1999/REC-html401-19991224/">http://www.w3.org/TR/1999/REC-html401-19991224</a></cite>.

Though the HTML or
XHTML version
of your specification is always the definitive one, many editors find
an XML original easier
to work with, and sometimes an XML version is provided as an
alternative format. The W3C XML Specification DTD
(XMLspec) used to produce many of W3C's XML-related Recommendations can
facilitate this work. XMLspec is fully documented
[XMLSPEC]. Various XSLT style sheets are in use and continual
development to output the final technical report [XSLT]. For help with this process, you can ask
the experts on the public mailing list spec-prod@w3.org [SPEC-PROD].

The author may explain why if these key words are not used in the
RFC sense.

Where they are not required for
interoperation or to limit behavior which has potential for causing
harm these key words must not be used to try
to impose a particular method on implementors where the method is not
required for interoperability.

W3C uses Merriam-Webster's
Collegiate® Dictionary, 10th Edition
[M-W], on the Web as the spelling
arbiter because it is free, on-line, and available to every technical
report author and editor. If a word does not appear there, use the
American Heritage® Dictionary,
4th Edition [AH]. Other dictionaries
are used as needed (for example, Random House and Webster's unabridged,
Oxford and Oxford Concise).

W3C uses U.S. English (e.g.,
"standardise" should read "standardize" and "behaviour" should read
"behavior").

Form the plural of abbreviations, initialisms and acronyms without
an apostrophe (e.g., the plural of
URI is URIs not URI's). See the FAQ
"Infrequently Asked Questions Concerning the Proper Spelling of
'DTD' in its Plural Form" [PLURAL].

Spell out acronyms and initialisms in their first occurrence in
prose, for example, "Internet Engineering Task Force
(IETF)" or "Internationalization (I18N)." In
subsequent occurrences when they are not spelled out, use
abbr and acronym elements, and give them
title attributes. For the purposes of HTML and XHTML 1.0, mark up as an
acronym anything that can be pronounced as a word, and
mark up initialisms and abbreviations as abbr.

Check references (most commonly, for no full stop after the
et in et al.). Do
the entries match?

Unless intentionally referring to the latest document in a series,
always refer to specific W3C documents by using the "this version"
URI.

If you are referring to a W3C document using either its this
version or latest version URI, note whether the URI ends in a slash or not. These
identifiers do not end in an extension such as ".html".
Include the extension when intentionally referring to a specific
version (e.g., a GIF image where GIF and PNG are both available through
content negotiation).

Domains in examples adhere to section 3, "Reserved Example Second
Level Domain Names," in RFC 2606 [DOMAINS]. Use the domains
example.com, example.org, and
example.net for all examples. The Internet Assigned Numbers
Authority (IANA) reserves them for this purpose. If you need an
evocative name or the name of a business, use a machine name (e.g., http://cats.example.org).

When not addressed by second level example domains, top level
domains (TLDs) adhere to section
2, "TLDs for Testing, & Documentation Examples," in
RFC 2606
[DOMAINS]. Use
.test, .example, .invalid or
.localhost.

W3C publications are copyrighted by W3C, and W3C liability,
trademark and document use rules apply. Note that in general, one
should not use material (text, photo, audio) in examples when the
copyright is not held by W3C. If the group wishes to publish
copyrighted materials, it should contact the Team legal staff.

We recommend that each image be available as PNG, even if you use
content negotiation to serve alternative formats.

Give images a background color (e.g.,
white) so your technical report can be read with any style sheet
(e.g., with W3C's dark on light style
sheets, or a user style sheet that specifies a dark background).

Match image size to markup width and
height (or images will be distorted).

Large single files that may be easy to print and search may not be
easy to download. For large documents:

Divide the document logically, storing chapters in separate
files.

Offer a single-page, printable, searchable version of the
specification. This format may be compressed if large.

You can offer an archived version (zip, tar, tgz) of the separate
files. Provide all necessary file in archived versions including the
relevant style sheets. Don't link to images or style sheets not
included in the archive.

Thank you to Karl Dubost (W3C). Thank you to Philip Gallo for the
pencil image and to Paul Harmon and to E.K. for artwork used in earlier
versions. The following people contributed to this compilation:

All affiliated with W3C at the time, Dan Connolly, Ian Jacobs,
Joseph Reagle, Tim Berners-Lee, Karen MacArthur, and Håkon Wium Lie
wrote the majority of this guide in various incarnations since it
started in 1995.

2001-10-27: Removed most CSS. Responding to Björn Höhrmann's
comments: Added note to not use "you." Fixed references markup.
Mentioned two free spelling tools. Now say that filename extensions are
permitted when linking to a specific version. Corrected
alt text note to say that the text should replace the
image when possible. Added xml:lang attribute to 11.8.
Clarified reasoning behind not using "click here." Added to description
of archived versions.

2001-10-31: Moved punctuation from miscellaneous to a separate
section