This manual is a guide containing best current practice, written for editors and authors of W3C technical reports. No requirements
for W3C publications are in this document. All requirements for W3C
publications are in W3C
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
REQUIRED Technical Report Publication
called "pubrules" for short. Following the advice in this manual has
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
Polished at early public maturity levels, clean copy eliminates
multiple "typo" reports.
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
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
Make sure your technical report validates in the W3C Markup
Validation Service [VALIDATE]. Append ",validate" to a W3C
URI to invoke the
Make sure your technical report validates in the W3C
Service [CSSVALIDATE]. Append ",cssvalidate" to a
W3C URI to invoke the
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 guidelines in Internationalization Best Practices for Spec Developers [[INTERNATIONAL-SPECS]] when producing your specification. You might also find it helpful to complete a self-review early in the development process. If your specification touches on more complex issues, you can also reach out to the Internationalization Working Group for guidance.
Internationalization terminology, particularly terms related to Unicode, can be rather precise. To help avoid problems with the need to define these, import the [[Infra]] standard and [[I18N-GLOSSARY]]. Use the terms found in these documents instead of creating your own and link your use of these terms to the definitions found in these documents. Instructions on how to do this can be found in an appendix of the [[I18N-GLOSSARY]].
Write for a global audience
Keep in mind that W3C documents serve a global audience.
Avoid idioms that are U.S.- or English-specific in favor of more neutral language.
Choose examples that reflect a global audience. For example:
When creating user stories or other examples that feature people, choose example names that come from different cultures and regions. You can find suggestions here in [[INTERNATIONAL-SPECS]].
Choose more generic terms for field names, such as "postal code" instead of (U.S.-specific) "ZIP code" or "given name" instead of "first name".
In general, use [=locale-neutral=] representations of data values, such as dates, numbers, currency values, and so forth.
For time and date values, choose an unambiguous representation:
For date values that appear in prose, spell out the month (for example, 6 May 2003 or September 23, 2016). All numeric dates such as 5/6/03 or 6/5/03 are ambiguous. Some cultures will read the first example as "June 5" while other cultures will read the second example as that date.
For date values that appear in data, use a format derived from ISO8601, such as those found in [[RFC3339]] or those found in XML Schema Part 2: Datatypes ([[XMLSchema-2]].
Use U+XXXX syntax to represent [=Unicode code points=] in the specification. These are space separated when appearing in a sequence. No additional decoration is needed. Note that a [=code point=] may contain four, five, or six hexadecimal digits. When fewer than four digits are needed, the code point number is zero filled.
Unicode assigns unique, immutable names to each assigned [=Unicode code point=]. Using these names in your specification when referring to specific characters (along with the code point in U+XXXX notation) will help make your specification unambiguous.
There are cases where doing this is overly pedantic and detracts from usability, but be cautious about being so informal as to impair meaning.
Some notes about the markup used. The bdi element is used to ensure that example characters that are [=right-to-left=] do not interfere with the layout of the page. The lang attribute should be filled in with the most appropriate [[BCP47]] [=language tag=] to get the correct font selection (and other processing) for a given context. Examples in East Asian languages (such as Chinese, Japanese, or Korean) or in the Arabic script can sometimes require greater care in choosing a language tag.
W3C has no official translations of its technical reports. W3C does
encourage people to translate the technical reports and helps to track
translators and translations.
A central translation page includes links to pages that document
translations of particular specifications [TRANSLATE].
Make your specification more readable by adding markup to distinguish common words from keywords in your language. Mark up every occurrence. Use translate="no" as an attribute to communicate to translators that the keyword is part of the [=vocabulary=] of a formal language rather than part of the [=natural language=] text of the document. For example:
<p>The title attribute of these elements may be used
to provide the full or expanded form of the expression.
<p>The <code translate="no">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
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
See pubrules [PUBRULES] for
information about the use of "version" and "edition". "Level" and
"revised" are deprecated. Try not to invent a new titling
Capitalize title words following U.S. usage.
Editors and Authors
Managing Changing Affiliations
Editor/Author affiliations change over time. Here are examples that
illustrate the suggested approach for managing them.
Richard Ishida, W3C (and before at Xerox)
François Yergeau, Invited Expert (and before at Alis
Jane Doe, MyCompany (and before at ThierCompany, and at HisCompany,
and at HerCompany)
No longer editor
Martin J. Dürst (until Dec 2004 while at W3C)
Misha Wolf (until Dec 2002 while at Reuters Ltd.)
Tex Texin (until Dec 2004 while an Invited Expert, and before at
FitzChivalry Farseer (until Oct 2005 while at AnyCompany, and
before at ThisCompany, and at ThatCompany)
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
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
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?
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.
Clearly indicate on the errata page:
The last modified date for the errata page.
The URI of the
source document (i.e., the one with the
Where to find the latest version of the source document.
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
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
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
A sentence containing a text-only URI.
When available, a sentence ending in the latest version
<dt><a id="ref-XML1" name="ref-XML1">[XML1]</a></dt>
Markup Language (XML) 1.0 (Fourth Edition)</a></cite>,
T. Bray, J. Paoli, E. Maler, C. M. Sperberg-McQueen, F. Yergeau,
Editors. World Wide Web Consortium, 16 August 2006, edited in place
29 September 2006. This edition of the XML 1.0 Recommendation is
http://www.w3.org/TR/2006/REC-xml-20060816/. The <a
href="https://www.w3.org/TR/xml/">latest edition of XML 1.0</a>
is available at http://www.w3.org/TR/xml/.</dd>
Reference titles are recommended, not the "URI-in-your-face" idiom, as link
text; see [REF-TITLES]. For
example, Do use: <cite><a
Specification</a></cite>. Do not use:
For help with this process, you can ask
the experts on the public mailing list email@example.com [SPEC-PROD].
Normative & Informative sections
It is important that informative (non-normative) material
is clearly distinguished from normative material. To this end:
If the entire document is informative, say so at the top and
do not reference RFC 2119 or use RFC 2119 keywords
If some sections are informative, say so at the
start of each section, and do not
use RFC 2119 keywords in those sections
Figures, examples and notes are assumed to always be informative.
To avoid repetition, each figure, example or note does not say this.
to avoid breaking user expectations,
document editors MUST NOT make any
figure, example or note normative.
RFC 2119 Key Words
Recent changes to ReSpec mean this is not the case in this document (which is based upon ReSpec), nor in other ReSpec generated documents.
Adhere to and credit RFC 2119 Key words for use in
RFCs to Indicate Requirement
(e.g., "MUST", "MUST NOT", "REQUIRED").
When these key words are used in the RFC sense, make them UPPERCASE, enclose
them in the em element, and style them with CSS class of rfc2119 to make the UPPERCASE readable.
The author may explain why if these key words are not used in the
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.
This section refers to editorial practice at W3C. It touches on
grammar, spelling, punctuation, case, linking, appearance and
Delete repeated words.
Check subject-verb agreement.
Break long sentences.
Eliminate contractions (e.g., "don't"
should read "do not")?
Spell-check using a U.S. English dictionary. Append ",spell" to a
W3C URI to invoke
W3C's spell checker.
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
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].
Use correct punctuation. A hard copy of The Chicago Manual of
Style or The Gregg Reference Manual may be of some
Remember you are typing HTML or XML not TeX. Use quotation marks
rather than grave accents and apostrophes to quote text (e.g., ``value'' should read "value").
Case, Combining Words, and Hyphenation
Capitalize W3C entities to match the W3C Process
(e.g., Working Group, Recommendation).
Make the case, number of words, and hyphenation in terms match
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 elements, and give them
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"
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
Visible URIs and
href attributes should have the same value.
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
.test, .example, .invalid or
Remember to validate markup in examples. Escaped characters pass
through routine validation.
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 (firstname.lastname@example.org).
Use CSS with
div elements to mark up examples, as is done in the
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).
Mark up data table headers with th not by
bolding a td.
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
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.
Following the W3C Code of Conduct,
W3C specifications are expected to be
inclusive and facilitate diversity. As such, editors and authors are strongly encouraged
to use a neutral and inclusive language to ensure the best environment possible for the
whole W3C community.
Either capitalize or lower case "Web" (e.g., Web developer or web developer, Web project or web project, Web page or web page, Web application or web application
one word, either capitalize or lower case
Web page, web page
two words, either capitalize or lower case "Web"
Web site, web site, website
two words (capitalize or lower case "Web") or one (lower case)
World Wide Web
three words, no hyphen
not W3C NOTE
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.
Judy Brewer (W3C),
Martin Dürst (W3C),
Max Froumentin (W3C),
Hugo Haas (W3C),
Dominique Hazaël-Massieux (W3C),
Bob Hopgood (Oxford Brookes University),
Paul Grosso (Arbortext),
Daniel Dardailler (W3C),
Richard Ishida (W3C),
Charles McCathieNevile (W3C),
Steven Pemberton (W3C),
Addison Phillips (Invited Expert),
Stuart Williams (Hewlett-Packard),
and François Yergeau (Alis Technologies)
all contributed valuable comments.