Also On This Page →

Publication Policies

Resources

Tools

editor's red and blue pencil

Status of This Document

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.

Table of Contents

  1. Introduction
  2. Validation
  3. Accessibility
  4. Internationalization
  5. The Parts of a Technical Report
  6. Errata
  7. References
  8. Revisions
  9. XML, XMLspec, XSLT and Production
  10. RFC 2119 Key Words
  11. Editorial Guidelines
  12. Internet Media Types
  13. Commonly Misspelled Terms
  14. Acknowledgments
  15. References
  16. Change History
  17. To Do List

1. Introduction

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 Policy [PUBRULES], called "pubrules" for short. Following the advice in this manual has benefits:

Chapter 2 covers validation. Chapters 3 and 4 cover accessibility and internationalization. Chapter 5 describes parts of a W3C technical report. Chapters 6, 7, and 8 cover errata, references and revisions. Chapter 9 introduces XMLspec and XSLT. Chapter 10 addresses RFC 2119 key words. Chapter 11 presents editorial guidelines, and, finally, chapter 12 documents commonly misspelled terms.

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].

2. Validation

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

3. Accessibility

4. Internationalization

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.

4.1 Unicode

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]:

  1. by codepoint (e.g., U+002E)
  2. by formal Unicode name (e.g., full stop); see [CHARTS]
  3. by Unicode alias (e.g., dot, or decimal point, or period); see [CHARTS]

4.2 Translations

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.

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.

4.3 Style for Dates

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.

5. The Parts of a Technical Report

As of November 2005, pubrules [PUBRULES] includes a technical report template.

5.1 Document Title

The title of your document in the document head and on the technical reports index [TR] will read as follows. Optional elements are in square brackets.

Title [(ACRONYM)] ["Specification"] ["Part" Part_Number] [: Subtitle] ["Module"] [(nth "Edition")] ["Version" Version_Number]

See pubrules [PUBRULES] for information about the use of "version" and "edition". "Level" and "revised" are deprecated. Try not to invent a new titling convention.

Capitalize title words following U.S. usage.

5.2 Editors and Authors

5.2.1 Managing Changing Affiliations

Editor/Author affiliations change over time. Here are examples that illustrate the suggested approach for managing them.

Still editor
Richard Ishida, W3C (and before at Xerox)
François Yergeau, Invited Expert (and before at Alis Technologies)
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 Progress Software)
FitzChivalry Farseer (until Oct 2005 while at AnyCompany, and before at ThisCompany, and at ThatCompany)

5.3 Abstract

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.

5.4 Status Section

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:

6. Errata

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:

For example (shown here without links):

This document:
http://www.w3.org/Style/css2-updates/REC-CSS2-19980512-errata
Last revised:
$Date: 2014-08-05 18:26:01 $
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

On the errata page, list the newest entries nearer to the top.

Entries on an errata page

For each entry on the errata page, provide:

  1. A unique identifier
  2. The date it was added to the errata page
  3. A classification of the error (e.g., editorial, clarification, bug, known problem with the document itself)
  4. A short description of the problem and what part of the Recommendation is affected.
  5. Any proposed corrections and whether those corrections would affect conformance of documents or software
  6. Any normative corrections; see the section on Errata Management in the W3C Process Document ([PROCESS] section 7.6.1) for more information about normative corrections

Do no remove entries from the errata page; if a correction turns out to be incorrect, just add another entry (with a cross reference).

7. References

7.1 Bibliography Extractor

The W3C Bibliography Extractor [BIB-EXTRACT] will automatically generate a list of references in W3C style.

7.2 Citation

Reference links (e.g., "[XML]") link at least the first mention of a source to the References section and take the form:

<cite><a href="http://www.example.org/example">Full Name</a></cite> [<cite><a href="#ref-REFNAME">REFNAME</a></cite>]

Parentheses around square brackets can be omitted unless the parentheses would contain a section number.

References links occur at minimum at the first mention of the source. Spell out what the reference link refers to at least in the first occurrence, e.g.:

This is discussed in Namespaces in XML [XMLName].

or

This is discussed in the XML namespaces specification [XMLName].

and not

This is discussed in [XMLName].

7.3 Citing a Reference From Within a Document

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 when the link is unavailable (e.g., when printed).

Thus, for example:

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

7.4 References Section

7.5 Normative and Informative References

Normative references should be to stable and mature resources (e.g., only Recommendations).

8. Revisions

See the W3C Process Document ([PROCESS] section 7.6) for instructions on how to revise a technical report.

Note. When a document is revised, the original publication date remains the same (and on the technical reports index [TR] as well); see pubrules [PUBRULES] for more detail.

Be careful not to break links in revisions. If your document uses latest version URIs with a fragment identifier, unless those anchors are maintained across versions, links will break.

9. XML, XMLspec, XSLT and Production

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].

10. RFC 2119 Key Words

Adhere to and credit RFC 2119 Key words for use in RFCs to Indicate Requirement Levels [KEYWORDS] (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 to make the UPPERCASE readable.

<em title="MUST in RFC 2119 context"
       class="RFC2119">MUST</em>

.RFC2119 {
  text-transform: lowercase;
  font-style: italic;
}

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.

11. Editorial Guidelines

This section refers to editorial practice at W3C. It touches on grammar, spelling, punctuation, case, linking, appearance and markup.

11.1 Grammar

11.2 Spelling

11.3 Punctuation

11.4 Case, Combining Words, and Hyphenation

11.5 Miscellaneous

11.6 Linking

11.7 Using Examples

11.8 Images

11.9 Markup

11.10 Large Documents

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

12. Internet Media Types

13. Commonly Misspelled Terms

W3C has reviewed its technical reports one by one since November 1999, for typographical errors. The following words appear often in those reviews and are easy to misspell.

anti-alias
hyphenate
ASCII
all caps
base64
lowercase, one word
Bézier
always capitalize, and accent the first e
braille
capitalize only when talking about Louis Braille
built-in
hyphenate when used as an adjective or noun, not when built is a verb
DTDs
no apostrophe (see [PLURAL])
dingbat
one word
ECMAScript
one word, cap S
et al.
no full stop after "et"
full stop (.)
Full stop is the formal name. Dot and period are good aliases.
hash (#)
also number sign, usually not pound sign, crosshatch or octothorpe
heading
Term for h1-h6. Tables and HTTP have headers.
HTTP/1.0
needs slash when referred to as a protocol, none in free text
HTTP/1.1
needs slash when referred to as a protocol, none in free text
home page
two words
Java
cap J
JavaScript
cap S
Level 1, 2, 3
cap L when referring to a W3C technical report
line feed
two words
lowercase
one word
markup
one word
MIME type
now Internet media type (MIME type is two words. MIME is all caps.)
namespace
lowercase unless referring to the Namespaces in XML specification by name
number sign (#)
also hash, usually not pound sign, crosshatch or octothorpe
on-line
hyphenate
PDF
all caps
PostScript
cap S
read-only
hyphenate
ruby
lowercase
schema
lowercase
schemas
preferred to schemata
semicolon
one word
stand-alone
hyphenate
style sheet
two words
subset
no hyphen
superset
no hyphen
uppercase
one word
URI reference
usually not URI Reference or URI-Reference
URIs
no apostrophe (see [PLURAL])
user agent
lowercase
user interface
lowercase
Web (on its own)
always capitalize
Web (as part of a phrase)
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
Webmaster, webmaster
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)
well-formed
hyphenate
white space
two words
worldwide
one word
World Wide Web
three words, no hyphen
W3C Note
not W3C NOTE

14. Acknowledgments

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:

15. References

[AH]
American Heritage® Dictionary, 4th Edition. Houghton Mifflin Company, 2000. This book is on-line at http://www.bartleby.com/61.
[BIB-EXTRACT]
W3C Bibliography Extractor, Dominique Hazaël-Massieux, 2003. This tool is on-line at http://www.w3.org/2002/01/tr-automation/tr-biblio-ui.
[CHARMOD]
Character Model for the World Wide Web 1.0: Fundamentals, M. Dürst, F. Yergeau, R. Ishida, M. Wolf, and T. Texin, Editors. W3C work in progress, 2004. This version of the Character Model Fundamentals is http://www.w3.org/TR/2004/WD-charmod-20040225/. The latest version of the Character Model Fundamentals is available at http://www.w3.org/TR/charmod.
[CHARNAMES]
Unicode character names, M. Davis, M. Dürst, et al., 25-27 August 2001. This email thread is on-line at http://lists.w3.org/Archives/Public/www-international/2001JulSep/thread.html#133.
[CHARTS]
About the Online Code Charts, The Unicode Standard, Version 1.1 or later. The Unicode Consortium, 2001. Unicode code charts are on-line at http://www.unicode.org/charts/About.html.
[CHECKLINK]
W3C Link Checker, W3C QA Activity, 2000-2004. This service is on-line at http://www.w3.org/2000/07/checklink.
[CLICK-HERE]
Don't use "click here" as link text, Aaron Swartz. W3C QA Team, 2001. This QA tip is on-line at http://www.w3.org/QA/Tips/noClickHere.
[CSSVALIDATE]
W3C CSS Validation Service, W3C QA Activity, 1997-2004. This service is on-line at http://jigsaw.w3.org/css-validator.
[DOMAINS]
Reserved Top Level DNS Names, D. Eastlake, and A. Panitz. The Internet Society, June 1999. This RFC is available at http://www.ietf.org/rfc/rfc2606.txt.
[EDITORS]
W3C Editors Home Page, Dominique Hazaël-Massieux for the W3C Communications Team, 2003. This list of resources for editors is on-line at http://www.w3.org/2003/Editors/.
[GRM]
Frequently Asked Questions, The Gregg Reference Manual Instructor Site, Glencoe/McGraw-Hill, 2000. This FAQ is on-line at http://www.glencoe.com/ps/grm/faqs.
[IPRFAQ]
Intellectual Property FAQ, W3C, 20 June 2000. The latest version of this document is http://www.w3.org/Consortium/Legal/IPR-FAQ.
[KEYWORDS]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. The Internet Society, March 1997. This RFC is available at http://www.ietf.org/rfc/rfc2119.txt.
[M-W]
Merriam-Webster OnLine: Collegiate Dictionary, 10th Edition. Merriam-Webster, Incorporated, 2000. This book is on-line at http://www.m-w.com.
[MANAGE]
Document Management for Web Specs, D. Connolly. W3C, 1995-1999. This guide is on-line at http://www.w3.org/MarkUp/SGML/spec-mgmt.
[PERSISTENCE]
Persistence Policy, T. Berners-Lee, 1999. This policy is on-line at http://www.w3.org/Consortium/Persistence.
[PLURAL]
Infrequently Asked Questions Concerning the Proper Spelling of 'DTD' in its Plural Form, R. Cover, updated 4 January 2001 or later. This document is on-line at http://xml.coverpages.org/properSpellingForPluralOfDTD.html.
[PROCESS]
World Wide Web Consortium Process Document, I. Jacobs, Editor. W3C, 5 February 2004. The latest version of this document is http://www.w3.org/Consortium/Process.
[PRONOUNS]
Personal pronouns in specifications, M. Dürst, 13 May 2000. This email message is http://lists.w3.org/Archives/Public/www-international/2000AprJun/0058.
[PUBRULES]
Technical Report Publication Policy, I. Jacobs, and the W3C Team. W3C, 2000-2006. This document is on-line at http://www.w3.org/Guide/pubrules.
[REF-TITLES]
please use titles, not addresses, as link text, D. Connolly, 10 February 2000. This email message is on-line at http://lists.w3.org/Archives/Public/www-html-editor/2000JanMar/0103.
[REGISTER-1]
How to Register an Internet Media Type for a W3C Specification, J. Reagle, M. Dürst, P. Le Hégaret, 2002-2006. This Web page is on-line at http://www.w3.org/2002/06/registering-mediatype.
[REGISTER-2]
TAG Position on Use of Unregistered Media Types in W3C Recommendations, N. Mendelsohn, 4 August 2006. This email message is http://lists.w3.org/Archives/Public/www-tag/2006Aug/0012.
[SPEC-PROD]
spec-prod@w3.org. W3C, 1998-2001. Subscribe to this public mailing list at http://www.w3.org/Mail/Lists and view its archive at http://lists.w3.org/Archives/Public/spec-prod.
[STYLE-GUIDE]
Style Guide for Online Hypertext, T. Berners-Lee. 1992-1998. This guide is on-line at http://www.w3.org/Provider/Style.
[TR]
W3C Technical Reports and Publications, W3C, 1995-2001. This Web page is on-line at http://www.w3.org/TR.
[TRANSLATE]
Translations at W3C, W3C, 1997-2003. This Web page is on-line at http://www.w3.org/Consortium/Translation.
[UNICODE]
Citations and References, The Unicode Consortium, 2001. These instructions for citing Unicode are on-line at http://www.unicode.org/unicode/standard/versions/.
[VALIDATE]
W3C Markup Validation Service, W3C QA Activity, 1997-2004. This service is on-line at http://validator.w3.org.
[XHTML1]
XHTMLTM 1.0: The Extensible HyperText Markup Language, S. Pemberton et al. W3C, 2000. This version of XHTML is http://www.w3.org/TR/2000/REC-xhtml1-20000126. The latest version of XHTML1 is available at http://www.w3.org/TR/xhtml1.
[XMLSPEC]
Guide to the W3C XML Specification ("XMLspec") DTD, Version 2.1, E. Maler, Editor. W3C, 1997-2001. This documentation is on-line at http://www.w3.org/XML/1998/06/xmlspec-report-v21. The DTD is on-line at http://www.w3.org/XML/1998/06/xmlspec-v21.dtd.
[XSLT]
XSLT style sheets, N. Walsh et al. 2000-2001. These XSLT stylesheets for XMLspec are on-line at http://dev.w3.org/cvsweb/spec-prod/html.

External Links

The prose links to the following references as illustrations. They are informative, listed here for print use.

[CSS2]
Cascading Style Sheets, level 2 section 13.3.2, B. Bos, H. W. Lie, C. Lilley, and I. Jacobs, Editors. W3C, 1998. This example is on-line at http://www.w3.org/TR/1998/REC-CSS2-19980512/page.html#named-pages.
[EXCAL]
Excalibur, R. Zaccone, 2001. The Excalibur home page is http://www.eg.bucknell.edu/~excalibr/excalibur.html.
[HTML]
Introducing HTML 3.2. W3C, 1996-1999. This example is on-line at http://www.w3.org/MarkUp/Wilbur.
[ISPELL]
International Ispell, G. Kuenning et al. 1971-2001. The Ispell home page is http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html.
[P3PFAQ]
P3P and Privacy on the Web FAQ. W3C, 2000-2001. This example is on-line at http://www.w3.org/P3P/p3pfaq.
[SCHEMA-DATATYPES]
XML Schema Part 2: Datatypes sections 3.2.9 through 3.2.14.1, P. V. Biron, and A. Malhotra, Editors. W3C, 2001. The latest version of XML Schema: Datatypes is available at http://www.w3.org/TR/xmlschema-2.
[SCHEMA-PRIMER]
XML Schema Part 0: Primer section 4.2, D. Fallside, Editor. W3C, 2001. This example is on-line at http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/#DerivExt.
[XML]
Extensible Markup Language (XML) 1.0 (Fourth Edition) section 2.5, , T. Bray, J. Paoli, E. Maler, C. M. Sperberg-McQueen, F. Yergeau, Editors. W3C, 2006. This example is on-line at http://www.w3.org/TR/2006/REC-xml-20060816/#sec-comments.
[XML1]
Extensible Markup Language (XML) 1.0 (Fourth Edition), 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 latest edition of XML 1.0 is available at http://www.w3.org/TR/xml/.

16. Change History

17. To Do List


Ian Jacobs, W3C

Last modified: $Date: 2014-08-05 18:26:01 $