ARCHIVED Silver Style Guide

NOTE: Please use the new version of the Style Guide.

Before You Write

• Think of how readers will use the info in Silver.

• How will they react to it?
• What do they need to understand and use each guideline?

• Gather your ideas and think of the best way to structure them.
• As you write and trim unneeded content, be sure you convey complete thoughts about your topic.

Use Plain Language Principles

• Write directly to the reader (“you”). Explain to readers what they must or should do (“Use a heading for each section.”).
• Use a friendly and conversational tone, but don’t be overly familiar.
• Guide readers through the content.

• Be sure that each piece of content relates to the content immediately before and after it.
• Show readers how parts contrast or relate to each other.
• Use structure, such as steps and outlines, to make content flow smoothly.

• Write in the active voice.
• Use contractions (“can’t,” “won’t,” “it’s”).
• Use simple words with as few syllables as possible.
• View a list of words to avoid.
• Explain technical terms and jargon.

• When you introduce an acronym, first use the complete term and add the acronym in parentheses:

“The World Wide Web Consortium (W3C) is an international community… Contact W3C for more information.”

• If you use technical terms, explain them to the reader:

“That element is deprecated (it will be obsolete soon, and you should avoid using it now).”

• Use commonly-used words that readers use when they use search engines.
• Write short sentences: Use 10 or fewer words per sentence, when possible.
• Use no more than four to five sentences per paragraph, when possible.
• Avoid gerunds (“Write for the web” instead of “Writing for the web”).
• Don’t use casual, incomplete sentences (“Have questions?”)—use a noun and verb in each sentence (“Do you have questions?”).

Inclusive Language

• Use culturally-appropriate terms that are meaningful and respectful of all cultures..
• Use “people-first” language when writing about people with disabilities.

For example, use “people with disabilities” instead of “disabled people.”

• See the Disability Language Style Guide and the Diversity Style Guide for help with inclusive language.

Structure

• Use the “inverted pyramid” method: Put the most important content first and add supporting details after it. Use this method for writing headings, sentences, and paragraphs.
• Use headings and subheadings to break up content.
• Use bullets and numbered lists.
• Write about only one main idea or topic in a paragraph.
• Use enough white space to make content readable.

Formatting

• Avoid italics when possible.

Punctuation

• Use punctuation consistently in your writing.
• Use a serial comma in a list of three or more items in a sentence (“Writing in plain language helps people with cognitive disabilities, people with low-language proficiency, and people who are non-native language speakers.”).
• Quotation marks

• Use straight quotation marks when you write code samples (<img src="example.gif" alt="Image description">).
• Use curly quotation marks in narrative content (We learned about “alt text” for non-text content.).
• Use closing quotation marks after periods and commas (We use the term “alt attribute.”), and before other punctuation (What is an “alt tag”?).
• Place punctuation inside quotation marks when it's part of a quote (My teacher asked, “What is the best alt text for this graphic?”).