Structure and Formatting

Alt text

Alt text, or alternative text, is a short, written description of an image. Well-written alt text is important for accessibility and search engine optimization.

Your alt text should be descriptive enough that a person who is blind or has low vision has the same information that a sighted user would get from glancing at the picture. While there is technically no character limit for alt text, it is best to keep it short and sweet. The screen reader will pause after 150 characters and the user can press the down arrow key to continue reading.

If your photo has a caption that fully describes the picture, then alt text is not required because it would be redundant. However, there may be parts of the image that are obvious to sighted users (not needed in the caption) but need to be described in the alt text for people with visual disabilities.

Some guidelines for describing people in alt text:

  • Context will determine whether to mention race, ethnicity, gender, or age.
    • If the goal of your website is to encourage older patients to ask for help accessing their online health records, then age is relevant in a photo of a doctor helping an older patient access health records via an iPad.
    • Is it relevant that the doctor is African American? Or that she is a woman? Given the context, this may not be the most important information in this photo.
  • If you’re using stock images, you can use the gender, race, or age keywords given by the photographer.
  • If you’re using images of people you know, ask them their preferred pronouns and other ways they self-identify.
  • Otherwise, you can write around it by using job titles (doctor/patient, professor/student).

For more guidance on writing effective alt text, reference Tips for Writing Meaningful Alt Text - Level Access.

Headings

Headings help users and search engines to read and understand text. They act as signposts for readers and make it easier for them to figure out what a post or page is about.

Divide your content into sections and give each section a heading to help readers understand where they are in the document. It is good practice to make sure that your headings are informative to the reader; include a primary keyword or key phrase from the content of that section in your heading. Headings should generally be limited to 70–80 characters. Headings are in title case and should never be in all caps.

  • No end punctuation: Other than question marks, do not use other end punctuation (such as periods) in headings.
  • Spell out numbers: Spell out numbers in headings. Do not use digits (1, 2, 3…).
  • No ampersands in headings: Use ampersands (&) instead of and only when it is part of a company’s name or in a composition title.
  • No abbreviations or acronyms in headings: Screen readers rely on headings, so they should be written to sound natural. Avoid acronyms in headings as fully capitalized words may be read letter-by-letter by screen readers.
  • Exceptions are abbreviations that are so well-known the full spelling would be awkward and unnecessary, like HIV.

Hyperlinks provide users with additional information about a topic and can be used throughout your content. Links can be headlines, titles, statements, questions, or phrases. Make sure the linked text is clear, concise, and lets your reader know where you are sending them. Don’t bold your hyperlink or use any color other than the standard blue for URLs.

Use simple descriptive text for a hyperlink instead of the URL.

Exception: If referring to a particular website that is short and recognizable, you may use the website name as the link, but drop anything before the name of the site (http://www...) as in: vaccines.gov

Avoid using click here or go to this page and instead hyperlink keywords that describe the information included on the page that readers will be directed to visit. When choosing which text to hyperlink, find a balance between substance and brevity.

Link shorteners: The General Services Administration will sunset the Go.USA.gov URL shortener service on September 18, 2022. Please see their frequently asked questions for more information. In the absence of this service, reevaluate if your outreach channels need short links; perhaps the slightly longer link will be fine. If a short link is necessary, we suggest you use https://bitly.com/.

Lists

AP Stylebook: Lists
Lists make it easy to quickly comprehend complex information, help readers identify steps, save words and space on each page, and can make your logic and structure clearer.

Numbered lists should be used when the items have an implied sequence (first this, then this).
Bulleted lists should be used when items don't require a particular order.

Keep lists short. A full page of list items can be an indication that the content should be broken into additional sections or lists.

DO:

  • Use periods at the end of items in lists when the item is a complete sentence (like in this case).
  • Use parallel sentence structure when writing list items.
  • Capitalize the first word following the bullet.

DO NOT:

  • Add punctuation when the list items are fragments (this is a divergence from AP style).
  • Connect list items into a sentence with commas or semicolons. Bullets replace other sentence punctuation in lists.
  • Mix fragments and sentences in the same list.

QR codes

QR codes, or Quick Response codes, are two-dimensional codes on printed materials that are scanned with a smartphone, connecting individuals to additional online content or information. Keep in mind that QR codes should lead to mobile-friendly content. For QR code uses and resources, reference Digital.gov’s QR Codes Page.

Tables

Tables help convey complex information to users.

To create useful, effective tables:

  • Use tables when comparing numbers.
  • Use tables when presenting a series of “if, then” sentences.
  • Keep tables simple. Try to limit data tables to four columns, six rows, and 500 words.
  • Use short descriptive headings.

When building tables for a website:

  • Create the tables within your content management system (e.g., Drupal) — do not copy and paste from Word or another program.
  • Always assign a header row or column for compliance with Section 508 of the Rehabilitation Act of 1973. Screen readers rely on reading headers.
  • See the Section508.gov guidance for building accessible tables.

Title casing

In title case, the first letter of each primary word is capitalized, including the to be verbs (be, am, is, etc.). Articles, conjunctions, and prepositions with three or fewer letters are not capitalized. Use title case on all headings, including subheadings. Capitalize the second word in a hyphenated term in titles and headings, e.g., “Addressing HIV-Related Stigma.”

This Is an Example of Title Case

This page last reviewed on September 2, 2022