diff --git a/content/writing-style.md b/content/writing-style.md new file mode 100644 index 0000000..eb7893b --- /dev/null +++ b/content/writing-style.md @@ -0,0 +1,575 @@ +--- +title: "Writing Style" +permalink: /writing/style/ +ref: /writing/style/ +lang: en +github: + repository: w3c/wai-website-theme + path: content/writing-style.md +--- + +{::nomarkdown} +{% include box.html type="start" title="Summary" class="" %} +{:/} + +This WAI Style Guide sets guidelines for writing material for the WAI website. The purpose is to support: + +* readability +* consistency +* better, easier translations + +This is a living document that will be updated. + +Please send questions, comments, and suggestions to [wai-eo-editors@w3.org](mailto:wai-eo-editors@w3.org?cc=shawn@w3.org&subject=WAI%20Style%20Guide wai-eo-editors@w3.org). + +Related resources: [W3C Manual of Style](https://w3c.github.io/manual-of-style/), [draftstyleguide](https://www.w3.org/2018/07/DraftStyleGuide), [Internationalization Quick Tips for the Web](https://www.w3.org/International/quicktips/), [WAI Translation Glossary](https://github.com/w3c/translation-glossaries/blob/master/general.md) + +{::nomarkdown} +{% include box.html type="end" %} +{:/} + +{::options toc_levels="2..3" /} +{% include toc.html %} + +## Tone + +WAI content should convey these qualities: + +* Knowledgeable, Authoritative, Reliable, Credible +* Clear, Straight-forward +* Welcoming, Encouraging, Inspiring +* Modern, Up-to-date + +Different types of documents have different tone, for example: + +* Technical standards and most Policy resources: formal +* Standards support documents (WCAG Techniques, Understanding SCs, etc.): explanatory style +* Tutorials and how-to documents: concise and direct, also supportive and encouraging +* Stories of people with disabilities and some intros: friendly, narrative tone that invites exploration and engagement + +Generally avoid humor since it often does not work internationally. + +## Specifics + +### Punctuation + +* [comma before conjunction](http://en.wikipedia.org/wiki/Serial_comma) (also known as Oxford comma and serial comma), e.g.: apples, oranges, and bananas. +* punctuation outside quoted terms + * e.g.: This accessibility requirement is sometimes called sufficient "color contrast"; however, that is incorrect — technically it's "luminosity contrast". + * (Note: Many American-English style guides, including the Chicago Manual of Style, recommend periods and commas inside quotes. Most British-English style guides recommend punctuation outside quotes. Coding requires proper nesting. Because most of our audience is more focused on proper code syntax than on America-English syntax, we chose punctuation outside quoted terms.) +* Commas after introductory prepositional clauses, especially in sentences that are a bit long or complex. +* Comma (or colon) after "for example," and "e.g.,". Note: for Recommendations and other formal docs, probably better to use "for example" instead of "e.g.". +* Titles, headings, labels, menu items do not have terminal punctuation unless a question mark is required. +* "For example," OK as own sentence, even if not full sentence. This is generally easier to read, even though not formally correct. Often you can add a word or few to make it more smooth. + + When need to be grammatically correct, use semicolon: + > Introduce different user needs for audio and video content; for example, for people who don’t see the video and for people who don’t hear the audio. + + When want to have simpler structure, instead of just splitting up the sentence: + > Introduce different user needs for audio and video content. For example, for people who don’t see the video and for people who don’t hear the audio. + + Better to add words: + > Introduce different user needs for audio and video content. For example, explain the needs of people who don’t see the video and people who don’t hear the audio. + +See [Lists](#lists) section for punctuation of list items. + +### Capitalization + +* Titles, h1s, and menu items use headline-style capitalization (the first letter of major words is capitalized), unless otherwise noted below + * For EOWG Resources and most WAI pages: + * h2s and lower — usually use headline-style capitalization. Exceptions acceptable, especially for things like Tips + * For WCAG Understanding and Techniques documents: + * All headings use headline-style capitalization + * Exception: WCAG Techniques titles and h1 use sentence-style capitalization (since they are long phrases) +* web/Web capitalization + * web - lowercase as adjective, such as "web accessibility", "web page", "web application" + * Web - can capitalize when referring to the World Wide Web, or leave lower case for consistency within a document +* WCAG success criteria (lowercase) +* Working Groups, Task Forces + * XYZ Working Group - capitalize when talking about a specific working group, including, "the Working Group" without the name of the WG in the phrase. + * working groups - lowercase when talking generically about working groups. However, OK to capitalize if seems better for consistency within a doc. + * if in doubt, capitalize. + * same for Task Forces. +* phrases with acronyms, e.g.: RTC, AAC + * when used in a senetence, lowercase + * real-time communication (RTC) capitalization (RTC background) + * Real-Time Communication -- for headings and formal name of standards + * real-time communication and real-time communications -- for the generic idea in sentences + AAC example: "This registry supports augmentative and alternative communication (AAC) symbols in web content." + +See [Lists](#lists) section for info on capitalization of list items. + +### Spelling + +We generally use US/American spellings. One exception: "ageing". (ageing background) + +* dialogue / dialog + * dialog for dialog box + * dialogue for conversation, e.g., audio in transcriptions, captions, subtitles + +### Lists + +* Punctuation — + No punctuation after bullet/list items that are not complete sentences. (except in very formal documents) + Especially no semi-colons at the end of list items except in very rare cases in formal documents. + If complete sentences, then end with periods. Otherwise, no punctuation. + + > This include things like: + > * people using assistive technology + > * people using adaptive strategies + > * people using other things + + instead of + + > This includes things like: + > * people using assistive technology, + > * people using adaptive strategies, + > * people using other things. + +* Capitalization — can be either lowercase or initial caps, depending on the type of information. Most are lowercase — generally: + + * if the bullets could be in a single sentence, then lowercase + * if it is a heading (e.g., in-page contents), then initial caps + * if the bullet item is a full sentence or multiple sentences, then usually initials caps + + > This includes people using: + > * assistive technology + > * adaptive strategies + > * other things + + > The sections below address: + > * Assistive technology that people use + > * Adaptive strategies that people use + > * Other things that people use + +* Spacing — optionally, no space before lists, e.g., in [Contacting Orgs](http://www.w3.org/WAI/users/inaccessible.html) + Style the p and ul or ol like this: + + ``` +

...such as:

+