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

Unicode

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.

Use the Unicode character name to describe specific code points. Use of the character naming template is recommended.

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.

<span class="codepoint" translate="no"><bdi lang="??">&#xXXXX;</bdi> 
[<span class="uname">U+XXXX Unicode_character_name</span>]</span>

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.

• A central translation page includes links to pages that document translations of particular specifications [TRANSLATE].
• Read the W3C Intellectual Property FAQ, Can I translate one of your specifications into another language? and Can I create the "official" translation? ([IPRFAQ] sections 5.6 and 5.7).

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.

becomes:

<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 to titre.

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.

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.

Editors and Authors

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.

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:

• 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."

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 6.2.4) 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).

Bibliography Extractor

The SpecRef tool, an Open-Source, Community-Maintained Database of Web Standards & Related References, contains an exhaustive of references.

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

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

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 'outline' property of CSS Basic User Interface Module Level 3 ([CSS3UI], section 4.1).

References Section

• 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
  • A sentence containing a text-only URI.
  • When available, a sentence ending in the latest version URI

  Example:

  [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/.

  Markup for the example above:

  <dl>
  <dt><a id="ref-XML1" name="ref-XML1">[XML1]</a></dt>
  
  <dd><cite><a href="https://www.w3.org/TR/2006/REC-xml-20060816/">Extensible
  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 href="https://www.w3.org/TR/2016/REC-html51-20161101/">HTML 5.1 Specification</a></cite>. Do not use: <cite><a href="https://www.w3.org/TR/2016/REC-html51-20161101/">http://www.w3.org/TR/1999/REC-html401-19991224</a></cite>.

Normative and Informative References

See Normative References and considerations by the Team.

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. Thus, to avoid breaking user expectations, document editors MUST NOT make any figure, example or note normative.

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 class of rfc2119 to make the UPPERCASE readable.

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

.rfc2119 {
  font-style: normal;
  font-size: 0.875em;
}

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.

Grammar

• Delete repeated words.
• Check subject-verb agreement.
• Break long sentences.
• Eliminate contractions (e.g., "don't" should read "do not")?

Spelling

• Spell-check using a U.S. English dictionary. Append ",spell" to a W3C URI to invoke W3C's spell checker.
• Free dictionaries are also available on the Ispell home page [ISPELL] for UNIX and the Excalibur home page [EXCAL] for Mac OS.
• 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].

Punctuation

• Use correct punctuation. A hard copy of The Chicago Manual of Style or The Gregg Reference Manual may be of some help.
• 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 Document [PROCESS] (e.g., Working Group, Recommendation).
• Make the case, number of words, and hyphenation in terms match chapter 12.

Miscellaneous

• 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 title attributes.
• Check references (most commonly, for no full stop after the et in et al.). Do the entries match?

Linking

• 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).
• Visible URIs and href attributes should have the same value.

Using Examples

• 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.
• 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 (team-legal@w3.org).

• Use CSS with div elements to mark up examples, as is done in the HTML 5.1 ([HTML], section 4.2):

Images

• 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).
• See the Web Content Accessibility Guidelines Techniques for information about providing alternative text (alt) and long descriptions (longdesc) for images. Also, don't forget to spell-check your alternative text.

Markup

• Use markup as it is intended. The blockquote and ul and li elements were designed for quotations and lists and not for indentation. Use CSS instead.
• Remove extraneous non-breaking spaces.
• Mark up attributes and elements consistently.
• Make sure there are no font or basefont elements in your document.
• Make sure all table elements in your document are real data tables, not tables used for layout.
• Make sure there are no bgcolor, background, color, face, marginheight, marginwidth or size attributes.
• Give each page lang="en-US" on the html element for HTML, or xml:lang="en-US" lang="en-US" on the html element for XHTML syntax.
• Use the span element and lang and xml:lang attributes for language changes within a page.
• Make semantic distinctions using more than only color, for example, a font-style change, so that color-blind individuals can see a difference.
• Links with the anchor text "Click here" provide no context. The visitor may become lost not knowing where "here" is. See also Don't use "click here" as link text [CLICK-HERE].
• Mark up data table headers with th not by bolding a td.

Large Documents

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.

Inclusive terminology

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.

Here are proposed alternatives for some terms that PubRules (see list of terms in JSON) shows a warning about: