style-and-formatting.md

Style and Formatting

Style Elements

• ampersands: Do not use ampersands in headers and running text. Spell out “and.” (Exception: VR&E)
• bold: Use bold sparingly to draw the reader's attention to must-read information that can be a full sentence or two. Be careful not to overuse bold text within a single page--or across our pages generally--or it will lose its power of emphasis. (Use italics to emphasize a word or two within a sentence. See the italics entry.)
• days of the week and months: Spell out the days of the week and the names of months (Monday rather than Mon.; September rather than Sept.). If there are space constraints, abbreviate with Mon. and Sept. For help text, for instance, especially when it needs to fit into a box on the page, we often need to abbreviate as follows: Mon.‒Fri., 7:00 a.m.‒7:00 p.m. (CST), and Sat., 9:00 a.m.‒5:30 p.m. (CST). Use the en dash rather than the shorter-in-length hyphen to connect days of the week and months that are ranges.
• headers: Headline capitalization for the main title or name of the page. All subsequent subheads on that page should be sentence-style capitalization.
• italics: Use italics sparingly to emphasize a word or two in a sentence. Do not italicize an entire sentence as it is hard to read on the screen. (e.g., If you request the withdrawal before you receive notice that the appeal has been transferred to the Board, submit this statement to VBA.)
  • orange stripe header that concludes the breadcrumbs should be headline capped unless in the form of a question, in which case it is sentence capped. We are trying to avoid orange stripe headers in the form of a question, but occasionally it will be appropriate.
• piano keys: The language on a piano key needs to match in some way the header on the page where you land. It doesn’t have to be an exact match, but should share key words at least. Piano keys can be in the form of a question, but we don’t normally have orange stripe headers in the form of a question. They can work well together.
• space between sentences: Use only one space between sentences. Use two spaces between bold lead-ins and text.
• time zones: Place the abbreviation in parentheses following the time. Use the following abbreviations for time zones:
  • EST: eastern standard time
  • MST: mountain standard time
  • CST: central standard time
  • PST: Pacific standard time
• Yes, if: This section is roman, not bold, and is followed by a colon.

Numbers

• dates: Spell out the month rather than using numerals (except for 9/11). See the entry for "Days of the week and months."
• numbers: Use numerals for all numbers. Do not spell out any numbers.
• percentages: Use numerals rather than spelling out the number. Use the percentage symbol rather than the word “percent” (a combined disability rating of 70%) with no space between the numeral and the percent symbol. Note: vets.gov style deviates from 18F style for percentages. We take this approach for scannability and because we have a fair amount of text discussing disability ratings in the Disability section. Both AP and Chicago Manual of Style recommend our approach for technical or scientific writing. Disability ratings fall into this category of writing.
• phone numbers: I have seen some exceptions that make sense, but in general, do not use parentheses for the area code. For 800 numbers, use 1 before the area code: 1-800-578-5777; for all other phone numbers that are not 800 numbers, the 1 should not be used: 401-283-3542.
• phone numbers with an extension: Use clear language like "press 1" rather than something more vague like "option 1" or "choose option 1." For example: Please call 877-222-VETS (8387), then press 2, from 8:00 a.m. to 5:00 p.m. (EST).
• time/hours: Use numerals rather than spelling out the number. When indicating a time range, use the "from ... to" or "between ... and" construction (“6 to 8 weeks” or “8:00 a.m. to 5:00 p.m.”). Where there are space constraints, such as in a box or an application, you may use the en dash, which is a little longer (‒) than a hyphen or dash (-): Please call 800-123-4567 during business hours, 8:00 a.m.‒5:00 p.m. (EST) or Please call 800-123-4567 between 8:00 a.m. and 5:00 p.m. (EST) Do not combine the two constructions to use “from” with the dash like this: “from 8:00‒5:00.”
• hours of operation associated with a phone number: Monday‒Friday, 7:00 a.m.‒7:00 p.m. (CST), and Saturday, 9:00 a.m.‒5:30 p.m. (CST). Spell out days of the week, if possible. If there's not enough room, use: Mon.‒Fri.

Punctuation

• bulleted lists: Bulleted lists are valuable tools in plain-language writing — they’re easy to scan and can help organize important information. If a sentence lists more than three items or elements, it is best to break the sentence out into a bulleted list. When using bulleted lists:

  • Capitalize the first word of every bullet.
  • Don’t use commas or semicolons after points in a bulleted list.
  • Don't use a period at the end of the bullet unless it is a complete sentence.
  • Don't use a bulleted list for only 1 element.
  • If your list has more than 7 items, use subheads to break it up.
  • Keep list items short (1 or 2 sentences in length)
  • Keep bullets in the same list parallel in construction (for example, each bullet starts with a verb) and consistent in style, grammar, and use of punctuation.

  | Before | ---| ---------| ----------- | How it works | | Several military occupational specialties have a risk of exposure to asbestos, including mining, milling, shipyard work, insulation work, demolition of old buildings, carpentry, and construction. VA also recognizes a risk of exposure in the manufacturing and installation of flooring, roofing, cement sheet, and pipe products. If you served in one of these specialties, you should be tested for related health risks. |

  | After | ---| --------| ------------ | Do I need to get tested? | | If you had a job during your service where you might have had contact with asbestos, you need to get tested for health problems. | Get tested if you worked in:

  • Mining
  • Milling
  • Shipyards
  • Construction and carpentry
  • Knocking down old buildings (demolition)
  | | Get tested if you made or worked with products like:
  • Insulation
  • Flooring
  • Roofing
  • Cement sheet
  • Pipes
  |

In the After example:

• The header draws the reader in — it poses an important question that many readers will have.

• The first sentence clearly outlines what the reader needs to know and the action they need to take.

• Plain language creates a conversational tone — without complicated terms like “exposure” — while still conveying the seriousness of the subject.

• Bullets make it easier for readers to see at a glance which occupations might have put them at risk.

• comma: Use the serial comma (sometimes referred to as the Oxford comma).

• exclamation point: We don't use the exclamation point since it does not align with the vets.gov tone, which is warm and quiet.