From 586536a4c31de1af69a266eceb9946921a7ea4cd Mon Sep 17 00:00:00 2001 From: Tamsin Ewing Date: Mon, 20 Jul 2026 16:26:48 +1200 Subject: [PATCH 1/6] Create as one continuous page --- w3c-style-guide.md | 1329 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1329 insertions(+) create mode 100644 w3c-style-guide.md diff --git a/w3c-style-guide.md b/w3c-style-guide.md new file mode 100644 index 00000000..c7725348 --- /dev/null +++ b/w3c-style-guide.md @@ -0,0 +1,1329 @@ +--- +title: "W3C Style Guide" +lang: en +lead: "Follow these guidelines when writing materials for W3C." +resource: + title: "W3C Style Guide" +--- + +{% include toc.html %} + +## About this style guide + +This style guide promotes readability, consistency, and easier translation across W3C content. + +It's a living document. For the list of substantive changes, see the Changelog [Link coming]. + +The guidance is written for US English. Translators should follow the conventions of their target language. + +Following this guide helps: + +- make content easier for people with a wide range of English language proficiency to read and understand +- support translators by using clear, consistent language +- improve consistency across W3C publications +- reduce editorial corrections and reports of avoidable issues + +Keep in mind that W3C content serves a global audience and is often used as authoritative reference material. Prioritize clarity, simplicity, and long-term readability. Much of what we publish becomes part of the permanent web record under the [W3C Persistence Policy](https://www.w3.org/policies/uri-persistence/). + +## Structure and presentation + +### Structure + +#### Logical flow and order + +* Present what readers need to know or do first, followed by supporting details and background. +* Make connections between sections clear. For example, use wording that shows how one section builds on, contrasts with, or illustrates another. + +#### Using structural elements + +* **Headings:** + * Use headings and subheadings to group related ideas. + * Write concise, unique headings that clearly describe the content beneath them. + * Front-load headings with relevant keywords to aid readability. +* **Sentences:** + * Write simple sentences. + * Stick to one idea per sentence. + * Keep the subject and verb close together. + * Use [punctuation](/unified-style-guide/grammar/#punctuation) that helps readers understand how ideas relate to one another. + * If a sentence becomes complex with more than one dependent clause, consider dividing it into two grammatically complete sentences. + +* **Paragraphs:** + * Keep paragraphs short. + * Stick to one topic per paragraph. + * Make sure the paragraph content fits the topic of the heading it sits under. +* **Lists:** + * Use lists for steps, options, and related items. + +### Formatting + +#### Bold + +Use bold sparingly to highlight important or urgent information, such as names, dates, deadlines, or key actionable points. + +Avoid bolding text in whole paragraphs or sections. + +#### Italics + +Use italics to indicate foreign words that are not common in English. + +
+Example: + +The Japanese aesthetic of wabi-sabi values simplicity and imperfection. +
+ +Use italics sparingly to emphasize a word or phrase if it helps make the meaning clearer, especially to show differences between ideas. + +
+Example: + +This policy applies to new staff, not existing staff. +
+ +Avoid italicizing text in whole paragraphs and sections. + +## Tone, language and words + +### Tone + +* Authoritative and factual +* Clear and straightforward +* Inclusive and respectful + +### Language + +#### Write in plain language + +Plain language uses clear wording, structure and design. It helps readers easily: + +* find information +* understand it +* use it to complete tasks + +##### Techniques for writing in plain language + +###### Abbreviations + +Provide the full term with the abbreviation on first use. See [Expanding abbreviations](#expanding-abbreviations). + +###### Contractions + +Avoid negative contractions such as “can’t”, “don’t”, and “won’t”. + +Keeping the word “not” expanded is important because it may distinguish between right and wrong, lawful and unlawful, or safe and unsafe. Negative contractions can cause some readers to overlook the apostrophe and interpret a statement as positive. + +
+Examples: + + +
+ +Use simple positive contraction such as “it’s”, “you’re”, “we’ve” and they’ll, because they make text feel more conversational and friendly, and help readers absorb information faster. + +###### Personal pronouns + +Use “you” and “your” to address the reader. + +Use “we” when speaking for an organization (like W3C), but only when it’s clear who “we” refers to. + +###### Structure + +Break up information into smaller sections to make it easier to read. See [Using structural elements](#using-structural-elements). + +###### Verbs + +Do not turn actions into nouns. Use verbs instead. + +
+Example 1: + + + +Example 2: + + +
+ +###### Voice + +Write in the active voice; that is, the subject performs the action. + +Avoid the passive voice where possible. + +
+Example: + + +
+ +###### Words + +* Use everyday, familiar words. +* Avoid jargon and metaphors. +* Explain specialist terms on first use. +* Remove unnecessary words. + +
+Example of unnecessary words: + + +
+ +#### Write for a global audience + +W3C content is read and translated around the world. + +- Avoid culture-specific references. +- Use examples that reflect a variety of cultures and regions. +- Choose internationally understood terms, such as “postal code” instead of “ZIP code”, and “given name” instead of “first name” (and [do not assume everyone has a first and last name, or that a family name comes last](https://www.w3.org/International/questions/qa-personal-names.en.html)). +- Use internationally recognized formats for dates, times, numbers, currency, percentages and measurements to avoid ambiguity. + +#### Write inclusively + +##### Aged-inclusive language + +Only state or request someone’s age when it’s strictly relevant. + +- Use: Older people +- Avoid: Older users, old people, the elderly, seniors + +##### Disability language + +See Disability language [link coming] for guidance on people-first language, identity-first language, disability-specific terms, and terminology to avoid. + +##### Gender-inclusive language + +Use gender-neutral language, where possible. + +
+Example: + +Use “chair”, not “chairman”. +
+ +Avoid assumptions about gender. + +
+Example: + +Not all builders are male. +
+ +###### Pronouns: Gender inclusivity and translation considerations + +Use pronouns that are **inclusive** and **easy to translate** for W3C's global audience. + +Use a plural noun to avoid he/she, his/her: + +Avoid assuming gender by skipping "he/she" and "his/her", where possible. Use a plural noun instead. + +
+Example: + +Using the noun “developer”: + + +
+ +Use a noun instead of singular “they”: + +Singular, “they” can be: + +* hard to translate in some languages +* hard to understand for some people +* seen as grammatically incorrect by some people + +To avoid using singular “they”, use a noun instead. + +
+Example: + + +
+ +**Exceptions:** Use: + +* personal pronouns that real people use for themselves +* pronouns assigned to named personas + +##### Race-inclusive language + +Terms to avoid: + +* Master — instead, use “main” +* Whitelist — instead, use “allowlist” +* Blacklist — instead, use “denylist” + +### W3C key terms + +For correct usage and spelling of key terms, see the W3C Word List [link coming]. + +## Style for different content types (A–Z) + +### Abbreviations + +#### Expanding abbreviations + +Spell out an abbreviation the first time you use it on a page. Put the short form in parentheses afterwards. After that, you can just use the abbreviation. + +
+Example: + + +
+ +There are a few ways you can do this. See [techniques for expanding abbreviations](https://www.w3.org/WAI/WCAG22/Techniques/general/G102#related). + +**Exception:** If a term is widely known by its abbreviation, you do not need to spell it out. + +
+Examples: + +ARIA, CAPTCHA, GIF, HTML, PDF, WiFi +
+ +#### Re-expanding abbreviations + +* Independent sections: In sections that may be read independently of the main text, spell out the abbreviation again, followed by the abbreviation in parentheses. +* Change of context: If an abbreviation could have multiple meanings and the context changes, provide the full meaning to clarify which meaning is intended. + +#### Capitalization in expanded terms + +Use title case for proper names. + +
+Examples: + + +
+ +Use lowercase for common nouns. + +
+Examples: + + +
+ +#### Plural acronyms + +Form the plural of an acronym by adding a lowercase”s”. Do not use an uppercase “S” or an apostrophe. + +
+Examples + +* Use: PDFs +* Avoid: PDFS, PDF’s +
+ +#### Abbreviations to avoid + +* e.g.: Use “for example”. +* etc.: + * In general contexts, use “such as” to introduce one or more examples. + * Where the text might be used within a legal context, use “including, but not limited to,” to introduce a non-exhaustive list of examples. +* i.e.: Use “that is” or “in other words”. +* vs.: Use “versus”, “compared with”, or “in contrast to”. + +**Exception:** + +If space is limited (for example, in a table cell), you may use abbreviations carefully. Include a comma if it would normally follow the full phrase. For example, write “e.g.,” and “i.e.,” rather than “e.g.” and “i.e.”. + +### Dates + +Put the day first: + +
+Example: + +1 January (instead of January 1) +
+ +Do not use letter suffixes after the day: + +
+Example: + +30 April (instead of 30th April) +
+ +Use numbers for the day and year, words for the month: + +
+Example: + +31 May 2022 +
+ +If numbers only are required, such as in a form, use YYYY-MM-DD: + +
+Example: + +2025-10-21 +
+ +#### Relative dates and times + +- Avoid relative dates and times, such as tomorrow, last week, or next Thursday, unless the content will be updated promptly. +- Use a specific date, including the year, where appropriate, so the information still makes sense over time. + +
+Example: + +The deadline to complete the course is Friday, 27 November 2026. +
+ +**Exception:** + +Blog posts and other dated content can use relative dates because readers expect them to reflect when they were published. + +### Headings + +#### Correct heading hierarchy + +Nest headings properly. For example, `

` should not be followed by `

` or lower. + +See also the guidance on [how to write good headings](#using-structural-elements). + +#### Capitalization in headings + +Use sentence case, not title case, for headings

to
. + +**Exception:** Capitalize any terms in the heading that are proper names. + +#### Punctuation in headings + +Use no punctuation at the end of headings, unless a question mark is required. + +### Labels + +Use sentence case for labels in user interface elements. Avoid title case. This includes: + +*buttons +*links +*menu items +*form labels +*tabs +*navigation items + +Capitalize only the first word and any proper names. + +
+Example: + +*Use: Create account, Reset password. +*Avoid: Create Account, Reset Password. +
+ +### Links + +#### Link text + +Link text should describe the destination. + +
+Example: + +To write link text for a link that takes the user to a page titled “WAI Resources”: + +
    +
  • Avoid: “Click here”, “Learn more”, “Read more”
    • +
  • Use: “WAI Resources”
    • +
+
+ +On a given page, do not use the same link text for links that go to different destinations. + +#### In-line links + +Place links at the end of sentences, if possible. + +
+Example: + + +
+ +#### Links to definitions + +When linking to a definition or glossary entry, link only the first occurrence of the term in each distinct section. Avoid linking every occurrence of the same term within a paragraph or section. +Repeated links create visual clutter and make content harder to scan. + +#### Links for email addresses + +When linking to an email address, use the email address itself as the link text rather than the person's name. This helps people identify the destination before activating the link and makes it easier to copy or note the address. + +
+Example: + +Avoid: + +*Email any questions to the Support team. +*Contact Jane Smith. + +Use: + +*Email any questions to support@example.org. +*Contact Jane at jane.smith@example.org. +
+ +#### Links to non-HTML documents + +Include the file format so the user knows what to expect. + +
+Example: + +
    +
  • Avoid: To download the full report, see Annual Report 2025.
    • +
  • Use: To download the full report, see Annual Report 2025 (PDF).
    • +
+
+ +#### Links to non-public documents + +When linking to non-public content, indicate that access is restricted. Use a label such as: + +*Password protected +*Member only +*Restricted +*Internal +*Login required + +
+Example: + +Meeting minutes (Password protected) +
+ +#### Punctuation in links + +Add a full stop after the linked text if it ends a sentence. + +Do not add a full stop after a raw URL. + +### Lists + +#### Parallel structure + +Keep the same grammatical form for each list item: all noun phrases, all verb phrases, or all full sentences. + +
+Examples + +Avoid: + +*Gathering data to understand the audience. +*Content structure and writing +*Test and refine the content + +Use: + +*Gather data to understand the audience +*Structure and write the content. +*Test and refine the content. +
+ +#### Long list items + +When some items in a list consist of several sentences, consider if the list structure is particularly useful for conveying the information. If not, use regular paragraphs instead of a list. + +#### Capitalization and punctuation in lists + +##### Text that introduces a list + +End with a colon. + +
+Example: + +Web accessibility means that people can: + +
    +
  • perceive, understand, navigate, and interact with the web
    • +
  • contribute to the web
    • +
+
+ +##### List items are complete sentences + +Capitalize the first letter. + +End with a full stop or a question mark. + +
+Example: + +
    +
  • In spring I mulch the roses.
    • +
  • In summer I grow vegetables.
    • +
  • In autumn I sow and repair the lawn.
    • +
+
+ +##### List items are fragments or not complete sentences + +Begin each item with a lowercase letter (unless the first word is normally capitalized, such as a proper noun) + +End each item with no punctuation. + +
+Example 1: + +Shopping list: + +
    +
  • bread
    • +
  • milk
    • +
  • eggs
    • +
+ +Example 2: + +Your application must include the following documents: + +*a full résumé +*three letters of recommendation +*two forms of identification +
+ +##### List items complete the introductory phrase or sentence in the body text + +Treat all the items in the list as a grammatical part of the introductory phrase or sentence. + +Start with a lowercase letter, even if the list is a numbered list. + +End each item with no punctuation. + +
+Examples: + +To give your day structure, use the 1-3-5 Rule and focus on: + +
    +
  • one big task
    • +
  • three medium tasks
    • +
  • five small tasks
    • +
+ +To prepare for a productive day: +
    +
  1. wake up early
    2. +
  2. review goals
    3. +
  3. prioritize the most important tasks
    4. +
+
+ +##### List items that are a mix of complete sentences and fragments + +If you must mix sentences and fragments, start with a capital letter and end with a full stop or question mark for all items. + +### Numbers + +#### When to write as digits + +##### Ages, measurements, percentages, and ratios + +Always use a digit: + +
+Examples: + +
    +
  • She is 5 years old.
    • +
  • They run 5 kilometres every day.
    • +
  • He is 6 feet tall.
    • +
  • We drink 2 litres of water a day.
    • +
  • I bought 2 kilos of tomatoes.
    • +
+
+ +#### Digits versus words + +##### Numbers showing quantity or order + +Numbers up to nine: use words. + +
+Examples: + +
    +
  • He invited nine friends.
    • +
  • She came first.
    • +
  • It was the ninth time this happened.
    • +
+
+ +Numbers 10 and above: use digits. + +
+Examples: + +
    +
  • They bought 10 plants.
    • +
  • I was 12th in the queue.
    • +
+
+ +**Exceptions:** + +* See [Ages, measurements, percentages, and ratios](#ages-measurements-percentages-and-ratios). +* Use words for very large, rounded numbers. + +
+Examples of writing very large numbers: + +1 million, 2.2 billion, 3.5 trillion +
+ +##### Start of a sentence + +Avoid starting a sentence with a digit. Use words or reword. + +
+Examples: + +
    +
  • Avoid: 10 of the 25 participants had issues completing the task.
    • +
  • Use:
    • +
      +
    • Ten of the 25 participants had issues completing the task.
      • +
    • Of the 25 participants, 10 had issues completing the task.
      • +
    +
+
+ +##### Related numbers + +With *related* numbers, where one number is usually written in digits and the other not, use digits for both. + +
+Example: + +We bought 1 bag containing 500 seeds. +
+ +##### Adjacent numbers + +With *adjacent* numbers that express different categories of numbers, use a mixture of words and digits. + +
+Example: + +The cook needs twelve 2-pound bags of flour. +
+ +##### Phone numbers + +Include the country calling code and, where applicable, the area code. + +
+Example: + +*Avoid: (212) 555-1234 +*Use: +1 212 555 1234 +
+ +#### Punctuation in numbers + +Use commas in numbers with more than three digits. + +
+Examples: + +
    +
  • 9,000
    • +
  • 9,990,900
    • +
+
+ +**Exceptions:** Use no punctuation for years, addresses, page numbers, or code line numbers. + +### Symbols + +Except where there is a lack of space (for example, in a table or chart), use words for the following symbols: + +* Ampersand: + * &: Use “and” instead. +* Number sign (octothorpe): + * #: Use “number” or a suitable noun instead. + +
+Examples: + +
    +
  • Number 3 is correct.
    • +
  • Statement 2 is true.
    • +
+
+ +### Times + +* Use the 24-hour clock. + +For an audience in a particular location, use the local time zone. + +For a global audience, always schedule for the time zone “UTC” (Universal Coordinated Time). + +
+Example + +10:00 UTC +
+ +In a sentence, do not use the en dash. Use words instead, such as “from … to” or “between … and” instead. + +
+Examples: + +
    +
  • The meeting is from 09:00 to 10:30.
    • +
  • They agreed to meet between 13:00 and 15:00.
    • +
+
+ +## Grammar + +### Capitalization + +#### Abbreviations + +See [Capitalization in abbreviations](#capitalization-in-expanded-terms). + +#### All caps + +Avoid using all capital letters for words (except acronyms). + +#### Glossaries + +Use lowercase for glossary terms (except for proper names). + +
+Example + +
+
browser
+
A web client that allows a human to read information on the web
+ +
Enquire Everything
+
A 1980 program named after the Victorian book Enquire Within upon
+ +
information space
+
The abstract concept of everything accessible using networks: the web
+
+ +#### Headings + +See [Capitalization in headings](#capitalization-in-headings). + +#### Lists + +See [Capitalization and punctuation in lists](#capitalization-and-punctuation-in-lists). + +#### Official names versus common terms + +Capitalize terms when they form part of an official name. + +Use the full official name where practical to reduce ambiguity. + +Use lowercase when referring to the same thing generically rather than by its official name. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Generic termExample official name
advisory boardW3C Advisory Board
advisory committeeW3C Advisory Committee
code of conductW3C Code of Conduct
interest groupWAI Interest Group
memberW3C Member
participantW3C Participant
patent policyW3C Patent Policy
process documentW3C Process Document
recommendationW3C Recommendation
staff contactW3C Staff Contact
statementW3C Statement
task forceCOGA Task Force
working groupARIA Working Group
workshopW3C Workshop
+ +##### Do not abbreviate an official name + +Use the full official names where practical to reduce ambiguity. + +
+Examples: + +Use: + +* W3C Advisory Board +* WAI Interest Group +* ARIA Working Group + +Avoid: + +* Advisory Board +* Interest Group +* Working Group +
+ +##### Plural forms + +Use lowercase for generic references, even when the singular form is capitalized as part of an official name. + +
+Examples: + +* The organization joined as a W3C Member to work with us. +* Organizations of all sizes and all types are W3C members. +* We have published a new W3C Recommendation. +* We have published several W3C recommendations. +* WCAG 2.2 includes Success Criterion 2.5.8 Target Size (Minimum). +* WCAG 2.2 contains 86 success criteria. +* The Accessibility Guidelines Working Group is discussing the issue. +* Three working groups support W3C's mission to make the web accessible to people with disabilities. +
+ +### Punctuation + +Punctuation helps to separate ideas, signal relationships between ideas or emphasize ideas. Each punctuation type has a different purpose. + +#### Brackets + +##### Parentheses (round brackets) + +Use parentheses sparingly within a simple sentence in the following scenarios: + + Provide the abbreviation for a term + +
+Example: + +Internet of Things (IoT) +
+ +Scenario 2: Clarify something in a short aside + +
+Example: + +Captions (called “subtitles” in some areas) provide content to people who are deaf and hard-of-hearing. +
+ +Scenario 3: Signal an optional plural + +
+Example: + +Test(s) +
+ +##### Square brackets + +Use square brackets in quotations to show you have altered or added something to the original quoted material. + +Use to: + +- insert an explanation in a direct quotation +- indicate something that’s been incorrectly written in a direct quotation +- add some text within a direct quotation in order to clarify something +- modify a direct quotation so that it fits grammatically within the surrounding text + +
+Examples: + +- Adding an explanation: “The council approved the project after reviewing the trial results [from an earlier study].” +- Indicating an error: The letter states, “The committee beleives [sic] the proposal will succeed.” +- Clarifying something: The report says the system must be updated because “it [the software] is outdated. +- Modifying to fit grammar: The policy explains that “[t]he system must be reviewed every year.” +
+ +#### Colons and semicolons + +##### Colons + +Use a colon to introduce the main idea(s). It gives the sense of “as follows.” + +In paragraph text: Use lowercase for the word following a colon + +
+Example + +They had one goal: to finish the marathon +
+ +In titles or labels: Use uppercase for the word following a colon. + +
+Examples + +- Group Note: Use of Large Language Models in standards work +- Contact us: Email support@example.com. +
+ +**Note:** A complete sentence must precede a colon. + +##### Semicolons + +Use a semicolon in the following scenarios: + +Scenario 1: Use a semicolon to combine two related ideas in a simple sentence. The text before and the text after the semicolon should both be grammatically complete sentences. + +
+Examples: + +- The rule is simple; applying it consistently is harder. +- The first draft focused on accuracy; the second focused on readability. +
+ +Scenario 2: Use a semicolon to break up complex lists in a sentence or bulleted item that contains internal commas. + +
+Example + +The conference has attendees from Seattle, Washington; New Delhi, India; and Nairobi, Kenya. +
+ +#### Commas + +In a phrase listing three or more items, place a comma before the final conjunction ("Oxford comma"). + +
+Example: + +I bought apples, oranges, and bananas. +
+ +#### Dashes and hyphens + +##### Em dash (—) {#em-dash} + +Use an em dash to add clarification, explanation, or emphasis after a complete clause. + +Put a space before and after an em dash. + +The part after the dash does not have to be a complete sentence. + +
+Examples: + +- WCAG 3 will have a different structure, different conformance model, and broader scope — see WCAG 3 Introduction. +- Write in the active voice — that is, the subject performs the action. +- Our mission is to make the web work — for everyone. +
+ +**Note:** If using an em dash to combine related ideas makes a sentence long or complicated, use separate, grammatically complete sentences instead + +###### Em dashes in list items + +Use an em dash in a list item to separate a short term or phrase from its explanation or a clarification. + +
+Example: + +

Common roles include:

+
    +
  • author — writes the content
    • +
  • editor — reviews the content before publication
    • +
  • translator — translates the content into another language
    • +
+
+ +##### En dash (–) {#en-dash} + +* Use an en dash to indicate a range in numbers, such as in dates, pages, and sports results. +* Do not add a space before and after an en dash. + +
+Examples: + +
    +
  • The years 1990–2000 were transformative.
    • +
  • Read pages 10–15.
    • +
  • They defeated the defending champions 106–76.
    • +
+
+ +##### Hyphen (-) + +Use a hyphen to join compound adjectives. + +
+Examples: + +
    +
  • peer-to-peer connection
    • +
  • short-term memory
    • +
  • well-known technique
    • +
+
+ +**Note:** Hyphens can change the meaning of a phrase: + +- “small-business owner” versus “small business owner” (an owner of a small business or a business owner who is small?) +- “little-used car” versus “little used car” (a car that has been used very little, or a used car that is small?) + +Do *not* hyphenate: + +* an adverb that ends in “ly” +* an adverb that follows a noun + +
+Examples: + +
    +
  • They are two closely related concepts.
    • +
  • The technique is well known.
    • +
+
+ +Use a hanging hyphen when two compound adjectives modify the same noun. + +
+Example: + +The pre- and post-deployment stages are equally important. +
+ +For guidance on terms we no longer hyphenate and are written as one word, see the [W3C Word List](#w3c-word-list). + +#### Ellipsis (...) + +Use an ellipsis to show: + +* missing words +* a pause +* something left unsaid + +Add a space before and after an ellipsis. + +
+Example: + +I was wondering … but it’s probably not important. +
+ +#### Headings + +See [punctuation in headings](#punctuation-in-headings). + +#### Links + +See [punctuation in links](#punctuation-in-links). + +#### Lists + +See [punctuation in lists](#capitalization-and-punctuation-in-lists). + +#### Numbers + +See [punctuation in numbers](#punctuation-in-numbers). + +#### Quotation marks + +##### Double quotation marks + +Use double quotation marks to reference a term. + +
+Example: + +This accessibility requirement is sometimes called “sufficient color contrast”; however, the technical term is “luminosity contrast”. +
+ +##### Single quotation marks + +Use single quotation marks for a quotation inside a quotation. + +**Note:** With nested quotes, the full stop remains inside both the single and double quotation marks. + +
+Example + +Maria said, "The reviewer described the proposal as 'well structured and easy to follow.'" +
+ +##### Scare quotes + +Avoid using quotes in a way that could be taken to suggest irony or in a non-standard way. For more information, see [scare quotes](https://en.wikipedia.org/wiki/Scare_quotes). + +#### Slashes + +##### Forward slash + +Generally, use a forward slash only in dates, fractions, and URLs. + +Avoid using a forward slash as a substitute for words. + +For two things that have a close relationship, use a hyphen or words like “and” or “or” instead. + +
+ +Example 1: Close relationship + +
    +
  • Avoid: The issue was part of the larger nature/nurture debate.
    • +
  • Use: The issue was part of the larger nature-nurture debate.
    • +
+ +Example 2: Equal relationship + +
    +
  • Avoid: The project examines cause/effect relationships.
    • +
  • Use: The project examines cause-and-effect relationships.
    • +
+ +Example 3: Either or both + +
    +
  • Avoid: Add a potato and/or an onion.
    • +
  • Use: Add a potato, or an onion, or both.
    • +
+
+ +Example 4: Alternative + +
    +
  • Avoid: If/when I have a dog, I’ll need a fenced yard.
    • +
  • Use: If or when I have a dog, I’ll need a fenced yard.
    • +
+ +**Exception:** You may use a forward slash to show an alternative if it's clearer than using words. + +
+Example: + +
    +
  • Avoid: In inclusive writing, avoid gender pronouns (she or her, he or his).
    • +
  • Use: In inclusive writing, avoid gender pronouns (she/her, he/his).
    • +
+
+ +### That versus which + +That: Introduces essential information needed to understand the sentence + +
+Example: + +The time is essential to identify specific meetings: “The meeting that starts at 10:00 is online. The other meetings are in-person.” +
+ +Which: Introduces extra information that is not essential. + +
+Example: + +The time is not essential: “The meeting, which starts at 10:00, is online.” +
+ +### Verb agreement with collective nouns + +Use a singular verb with collective nouns when referring to the group as a single entity. + +
+Examples: + +- Avoid: The working group have published a draft. +- Use: The working group has published a draft. +
+ +**Exceptions:** + +Exception 1: Use a plural verb if members act independently. + +
+Example + +The staff have handed in their separate reports. +
+ +Exception 2: The following collective noun always takes a plural verb: + - people: The people are waiting. + +## W3C word list + +@@ + From af1a1dd7e0183c1d9ad26c247434900b36e9e29f Mon Sep 17 00:00:00 2001 From: Tamsin Ewing Date: Mon, 20 Jul 2026 20:52:27 +1200 Subject: [PATCH 2/6] Add W3C Word List --- w3c-style-guide.md | 205 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 203 insertions(+), 2 deletions(-) diff --git a/w3c-style-guide.md b/w3c-style-guide.md index c7725348..ad160024 100644 --- a/w3c-style-guide.md +++ b/w3c-style-guide.md @@ -1323,7 +1323,208 @@ The staff have handed in their separate reports. Exception 2: The following collective noun always takes a plural verb: - people: The people are waiting. -## W3C word list +## W3C Word List -@@ +
+
accessible
+
Use accessible only when referring to accessibility for people with disabilities, or to places that disabled people can easily reach or enter. Do not use it to mean convenient, available, or easy to use. Example: Avoid: “The gardens are accessible to the public.” Use: “The gardens are open to the public.”
+
abort
+
Avoid. Use cancel.
+
anti-alias
+
Hyphenate.
+
ASCII
+
Use all caps.
+
back end, back-end
+
Use back end as a noun: “Data is processed by the back end.” Use back-end as an adjective: “We rely on a back-end server.” See Hyphens.
+
base64
+
Lowercase and write as one word.
+
Bézier
+
Always capitalize and include the accent on the first e.
+
blacklist
+
Avoid. Use denylist. See Race-inclusive language.
+
braille
+
Lowercase unless referring to Louis Braille. See Disability language.
+
built-in
+
Hyphenate when used as an adjective or noun. Do not hyphenate when "built" is a verb. See Hyphens.
+
checkbox
+
Write as one word.
+
click (versus select)
+
Use click when instructing a user to activate an interactive element, such as a button or link. For example, avoid “Select the Submit button.” Instead use: “Click the Submit button.”
+
color blind
+
Avoid when referring to people. Use “people who cannot distinguish between certain colors (often called ‘color blindness’).” When referring to the medical condition, use color vision deficiency. See Disability language.
+
color space
+
Write as two words.
+
data
+
Treat as singular. Write “The data is transferred,” not “The data are transferred.” See Verb agreement.
+
dingbat
+
Write as one word.
+
DTDs
+
Do not use an apostrophe. See Plural acronyms.
+
ECMAScript
+
Write as one word and capitalize the "S".
+
email
+
Write as one word. Do not hyphenate.
+
end user
+
Write as two words.
+
et al.
+
Do not place a full stop after "et".
+
filename
+
Write as one word.
+
for instance
+
Avoid. Use for example. See Plain language.
+
front end, front-end
+
Use front end as a noun. Use front-end as an adjective. See Hyphens.
+
full stop (.)
+
Use full stop as the formal name.
+
grandfather
+
Avoid. Use legacy. See Gender-inclusive language.
+
hand-eye coordination
+
Use hand-eye coordination, not "eye-hand coordination".
+
hard-coded
+
Hyphenate.
+
hash (#)
+
Also called a number sign. Usually avoid "pound sign", "crosshatch", and "octothorpe".
+
header
+
Use header for table headers and HTTP headers.
+
heading
+
Use heading for headings marked up with h1 through h6.
+
hearing-impaired, hearing impairment
+
Avoid. Use deaf with a lowercase "d", unless a person or community prefers another term. See Disability language.
+
home page
+
Write as two words.
+
hostname
+
Write as one word.
+
HTTP/1.0, HTTP/3
+
Use the slash when referring to the protocol name. Omit it only where established usage in running text requires a different form.
+
internet
+
Lowercase.
+
italics
+
Use the plural form.
+
its, it’s
+
Use its as the possessive form. Use it’s as the contraction of "it is" or "it has". Example: “It’s a dog wagging its tail. It’s been its best year.”
+
Java
+
Capitalize the "J".
+
JavaScript
+
Capitalize the "J" and the "S".
+
Level 1, Level 2, Level 3
+
Capitalize Level when referring to a level in a W3C technical report.
+
line feed
+
Write as two words.
+
log in, login
+
Use log in as a verb. Use login as a noun or adjective.
+
loss
+
Avoid as a general description that includes congenital conditions. Use it when describing a change, such as “As we age, we may experience hearing loss.” See Disability language.
+
lowercase
+
Write as one word.
+
markup
+
Write as one word. Do not hyphenate.
+
master
+
Avoid. Use main. See Race-inclusive language.
+
metadata
+
Write as one word. Do not hyphenate.
+
million
+
Do not abbreviate within a sentence. Use M for "mega" only with care and where the meaning is clear.
+
MIME type
+
Prefer Internet media type. If using MIME type, write it as two words and use all caps for MIME.
+
mouse click
+
Write as two words. Check whether you mean a mouse click specifically or any form of activation, including a finger tap or key press.
+
mouse pad
+
Write as two words.
+
namespace
+
Lowercase unless referring to the Namespaces in XML specification by name.
+
number sign (#)
+
Also called a hash. Usually avoid "pound sign", "crosshatch", and "octothorpe".
+
nobody
+
Write as one word.
+
no one
+
Write as two words.
+
offline
+
Write as one word. Do not hyphenate.
+
online
+
Write as one word. Do not hyphenate.
+
onscreen
+
Write as one word when used as an adjective.
+
pathname
+
Write as one word.
+
PDF
+
Use all caps. It does not need to be expanded on first use. See Abbreviations.
+
persons
+
Avoid. Use people.
+
please
+
Usually omit in informational content and instructions when it adds no meaning. See Omit unnecessary words.
+
plug-in
+
Hyphenate.
+
read-only
+
Hyphenate.
+
real-time communication
+
Lowercase, including when used with the acronym: real-time communication (RTC). Capitalize only when part of a proper name.
+
refer to
+
Avoid where see is clearer. See Plain language.
+
ruby
+
Lowercase for the typographic convention. Capitalize for the Ruby programming language.
+
sanity
+
Avoid in phrases such as "sanity check". Use a more precise term, such as coherence, confidence check, or validation. See Disability language.
+
schema
+
Lowercase unless part of a proper name.
+
schemas
+
Prefer schemas to "schemata".
+
select (versus click)
+
Use select when choosing from a set of options. Example: “Select an option from the dropdown menu.”
+
semicolon
+
Write as one word.
+
slave
+
Avoid. Use a context-specific alternative, such as replica. See Race-inclusive language.
+
speech recognition
+
Use for technology that converts spoken words into text for speech-to-text transcription, virtual assistants, and other speech user interfaces.
+
stand-alone
+
Hyphenate.
+
style sheet
+
Write as two words, except in the official name Extensible Stylesheet Language.
+
subset
+
Write as one word. Do not hyphenate.
+
superset
+
Write as one word. Do not hyphenate.
+
timestamp
+
Write as one word.
+
timezone
+
Write as one word.
+
touchscreen
+
Write as one word.
+
uppercase
+
Write as one word.
+
URI reference
+
Usually write URI reference, not "URI Reference" or "URI-Reference".
+
URIs
+
Do not use an apostrophe. See Plural acronyms.
+
usable
+
Use usable, not "useable".
+
user agent
+
Lowercase unless part of a proper name.
+
user interface
+
Lowercase unless part of a proper name.
+
visually impaired
+
Avoid. Use blind or a more specific term that reflects the person or group being described. See Disability language.
+
voice recognition
+
Use for technology that identifies who is speaking by analyzing vocal characteristics, such as voice biometrics used for authentication.
+
W3C Note
+
Use W3C Note, not "W3C NOTE".
+
web
+
Lowercase except when referring to the invention, as in “Sir Tim Berners-Lee invented the Web,” or when it is part of a proper name, such as World Wide Web Consortium or a job title such as “Senior Web Developer.”
+
web page
+
Write as two words.
+
webmaster
+
Write as one word.
+
website
+
Write as one word.
+
white space
+
Write as two words when used as a noun.
+
whitelist
+
Avoid. Use allowlist. See Race-inclusive language.
+
World Wide Web
+
Write as three words. Do not hyphenate.
+
worldwide
+
Write as one word.
+
zeros
+
Use zeros, not "zeroes".
+
From 7b10b954d1824ff1bde9d54c7540bdb4fa395886 Mon Sep 17 00:00:00 2001 From: Tamsin Ewing Date: Tue, 21 Jul 2026 12:34:57 +1200 Subject: [PATCH 3/6] Rename md file --- w3c-style-guide.md => style-guide/index.md.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename w3c-style-guide.md => style-guide/index.md.md (100%) diff --git a/w3c-style-guide.md b/style-guide/index.md.md similarity index 100% rename from w3c-style-guide.md rename to style-guide/index.md.md From 9a521ab77ae5a67f103e57c9c884ebd93fa1ba45 Mon Sep 17 00:00:00 2001 From: Tamsin Ewing Date: Tue, 21 Jul 2026 12:38:04 +1200 Subject: [PATCH 4/6] Correct md file name --- style-guide/{index.md.md => index.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename style-guide/{index.md.md => index.md} (100%) diff --git a/style-guide/index.md.md b/style-guide/index.md similarity index 100% rename from style-guide/index.md.md rename to style-guide/index.md From a1e734598d60432cee50e6537273ac2d40d29984 Mon Sep 17 00:00:00 2001 From: Tamsin Ewing Date: Tue, 21 Jul 2026 17:23:17 +1200 Subject: [PATCH 5/6] Create Gemfile.txt --- style-guide/Gemfile.txt | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 style-guide/Gemfile.txt diff --git a/style-guide/Gemfile.txt b/style-guide/Gemfile.txt new file mode 100644 index 00000000..39085670 --- /dev/null +++ b/style-guide/Gemfile.txt @@ -0,0 +1,4 @@ +source 'https://rubygems.org' +gem 'nokogiri' +gem 'rack', '~> 2.2.4' +gem 'rspec' \ No newline at end of file From 78a2a8672dba09b1c6b046afedf8b0b54617c671 Mon Sep 17 00:00:00 2001 From: Tamsin Ewing Date: Tue, 21 Jul 2026 17:23:43 +1200 Subject: [PATCH 6/6] Create toc.html --- _includes/toc.html | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 _includes/toc.html diff --git a/_includes/toc.html b/_includes/toc.html new file mode 100644 index 00000000..42c034f7 --- /dev/null +++ b/_includes/toc.html @@ -0,0 +1,32 @@ +## Table of contents + +
+
    +
    + + \ No newline at end of file