cme dev style guide logo cme dev style guide

Foundations

Web Elements

Every piece of content we publish is supported by a number of smaller pieces. This section lays out our style in regards to these web elements, and explains our approach to the tricky art of SEO.

Guidelines

Alt text

Alt text is a way to label images, and it’s especially important for people who can’t see the images on our website. Alt text should describe the image in a brief sentence or two.

For more on how and why we use alt text, read the Accessibility section.

Buttons

Buttons should always contain actions. The language should be clear and concise. Capitalize every word, including articles. It’s OK to use an ampersand in button copy.

Standard website buttons include:

Checkboxes

Use sentence case for checkboxes.

Use title case for menu names and sentence case for menu items.

Forms

Form titles should clearly and quickly explain the purpose of the form.

Use title case for form titles and sentence case for form fields.

Keep forms as short as possible.

Only request information that we need and intend to use. Don’t ask for information that could be considered private or personal, including gender. If you need to ask for gender, provide a field the person can fill in on their own, not a drop-down menu.

Headings and subheadings

Headings and subheadings organize content for readers. Be generous and descriptive.

Headings (H1) give people a taste of what they’re about to read. Use them for page and blog titles.

Subheadings (H2, H3, etc.) break articles into smaller, more specific sections. They give readers avenues into your content and make it more scannable.

Headings and subheadings should be organized in a hierarchy, with heading first, followed by subheadings in order. (An H2 will nestle under H1, an H3 under H2, and on down.)

Include the most relevant keywords in your headings and subheadings, and make sure you cover the main point of the content.

Use title case, unless the heading is a punctuated sentence. If the heading is a punctuated sentence, use sentence case. Use sentence case for subheadings regardless of end punctuation.

Provide a link whenever you’re referring to something on an external website. Use links to point readers to relevant content and trusted external resources.

Don’t include preceding articles (a, an, the, our) when you link text. For example:

If a link comes at the end of a sentence or before a comma, don’t link the punctuation mark.

Don’t say things like “Click here!” or “Click for more information” or “Read this.” Write the sentence as you normally would, and link relevant keywords.

Links should look different than regular copy, strong text, or emphasis text. They should have a hover state that communicates they’re interactive, and should have a distinct active and visited state. When setting the hover state of links, be sure to include focus state as well, to help readers using assistive technologies and touch devices.

Google’s developer documentation style guide doesn’t recommend opening links in a new tab or window by default. Google prefers to let the reader decide how to open the link.

Lists

Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction. Number your lists when the order (or priority) is important, like when you’re describing steps of a process. Don’t use numbers when the list’s order doesn’t matter.

If one of the list items is a complete sentence, use proper punctuation and capitalization on all of the items. If list items are not complete sentences, don’t use punctuation, but do capitalize the first word of each item.

Design your lists so their structure or syntax is parallel—more on that in the next section.

Uncanny Owl’s style for lists

For Uncanny Owl, preface all lists with colons, not periods. In other words, it doesn’t matter if the introductory sentence (lead-in) is complete. It still needs to end in a colon.

Bullet points should relate to the lead-in statement, not necessarily flow into each other. For each bullet, read it as if it follows the lead-in with the colon at the top, not the previous point. Then, make sure it still works (parallel structure). Here’s an example.

When you submit your article, you’ll need to include:

The first 2 list items above use parallel syntax. The third item does not.

Use title case for main or global navigation. Use sentence case for subnavigation.

Navigation links should be clear and concise.

Radio Buttons

Use title case for headings and sentence case for button fields.

Sometimes a long piece of copy lends itself to a list of related links at the end. Don’t go overboard—4 is usually plenty.

Related articles should appear in a logical order, following the step down/step up rule: The first article should be a step down in complexity from the current article. The second one should be a step up in complexity to a more advanced article.

If you can, avoid repeating links from the body text in related articles.

Titles

Titles organize pages and guide readers. A title appears at the beginning of a page or section and briefly describes the content that follows.

Titles are (you guessed it) in title case.

Don’t use punctuation in a title unless the title is a question.

SEO

We write for humans, not machines. We don’t use gross SEO techniques like keyword stuffing to bump search results. But we also want to make it easy for people and search engines to find and share our content. Here are some not-icky ways to do this: