What are you looking for?
Every piece of content we publish is supported by a set of smaller pieces. This section explains how we use these web elements.
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. It’s OK to use an ampersand in button copy when space is limited.
Forms
Form titles should clearly and quickly explain the purpose of the form.
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 user can fill in on their own, not a drop-down menu.
Headings and subheadings
Headings and subheadings organise content for readers. Be generous and descriptive.
Use sentence case.
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 act as signposts and guides to the flow of content and make it easier to scan.
Headings and subheadings should be organised in a hierarchy, with heading first, followed by subheadings in order. (An H2 will nestle under H1, an H2 under H3, and on down.)
Include the most relevant words in your headings and subheadings, and make sure you cover the main point of the content. Original and relevant headings are more important than keywords for Google search purposes.
Did we say to use sentence case? Use sentence case.
Feature headings
Make feature headings benefit-driven. Users don’t care about us, they want to know ‘What’s in it for me?’.
- What problems do we solve for the user?
- What is the outcome or result that users will experience?
- Explain how feature will make users’ lives better.
Limit feature headings to seven words – less is more.
Start feature headings with a verb. Preferably a success verb – high energy, active and positive. For example:
- Bring clarity and control to business
- Manage projects with accuracy and precision
- Make time count, drive project profitability
Links
Provide a link whenever you’re referring to something on an external website. Use links to point users to relevant content and trusted external resources.
Don’t include preceding articles (a, an, the, our) when you link text. For example:
- Yes: Read the knowledge base articles for details.
- No: Read the knowledge base articles for details.
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.
Lists
Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction. Number lists when the order is important, like when you’re describing steps of a process. Don’t use numbers when the list order doesn’t matter.
If one of the list items is a complete sentence, use proper punctuation and capitalisation on all the items. If list items are not complete sentences, don’t use punctuation, but do capitalise the first word of each item.
Navigation
Use sentence case.
Navigation links should be clear and concise.
Radio buttons
Use sentence case for headings and button fields.
Related articles
Sometimes a long piece of copy lends itself to a list of related links at the end. Don’t go overboard—four 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.
Try to avoid repeating links from the body text in related articles.
Titles
Titles organise pages and guide readers. A title appears at the beginning of a page or section and briefly describes the content that follows. A good title can carry a lot of the load in getting someone to read the beginning of the article — make it count.
Titles are in sentence case.
Don’t use punctuation in a title unless the title is a question.
SEO
We write for people, not toasters. We do want to make it easy for people and search engines to find and share our content, but not using old SEO techniques like keyword stuffing to bump search results. Focus on these techniques:
Organise your page around one topic. Use clear, descriptive terms in titles and headings that relate to the topic at hand.
Use descriptive headings to structure your page and highlight important information.
Give every image descriptive alt text.