Technical and interface writing

At IA, we often write things like guides, forms, and help messages. Most of the time, readers are learning something new. These tips will help you write clear, easy-to-follow instructions.

• Make it easy – Do the hard work so your readers don’t have to.
• Break it down – Write steps in order. Use short sentences and everyday words.
• Be specific – Use the exact names of buttons, menus, and links as they appear on the screen. Double-check spelling and capitalization.

Instead of:

Open a new meeting invitation.

Use:

In Google Calendar, click Create.

Start sentences with action words.

Instead of:

Help us understand what kind of help you need by creating an issue in Service Manager.

Use:

Create an issue with details about your request.
Or:
To get started, create an issue in Service Manager with details about your request.

Focus on what the reader can do.

Instead of:

You cannot continue without signing in.

Use:

Sign in to continue.

Titles and Headings

• Keep titles consistent across pages.
• Use the same style, like:
  • Nouns: Policies, Teams, Offices
  • Verbs: Create an account, File a report
• Use sentence case (capitalize only the first word and proper nouns).

Introductions

• Start with 2–3 sentences that explain what the page is about.
• This helps readers know they’re in the right place and improves search results.

Use clear verbs to explain what to do:

• Choose from drop-down menus
• Select or deselect checkboxes and radio buttons
• Click or tap buttons
• Follow or open links

Tables are good for showing data. Use them when you have:

• Two or more items (rows)
• Two or more values (columns)

Tips for tables:

• Line up numbers to the right and use the same number of decimal places (like “40.50” and “1.00”).
• Make sure column headings match the alignment of the data below them.

Most documents connect to other resources. Let readers know where to go next.

Example:
For more information, see the Code of Conduct.

If your content links to several documents, list the most important ones at the end.