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

About Silver’s Structure

• Silver's guidelines are technology neutral. Assume that what you write will apply to web and other formats. Ask yourself, “Does this guidance make sense for a mobile app, a virtual reality app, a home assistant, and other technologies?”
• Silver's methods are specific to a technology, like web HTML, web SVG, Android apps, etc. You may use terms—without defining them—that are common for a platform.

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.

For example:  “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

For example:  “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.
• Write in active voice (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 for writing headings, sentences, paragraphs, and links.  Start content with the most important piece of information so readers can get the main point, regardless of how much they read.  Put the most important content first and add supporting details after it.
• Use headings and subheadings to break up and organize 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?”).