An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock () or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Technical and interface writing

//FERMIN TEST

At IA, we often write technical documentation, guides, forms, and specific IA messages. In most of these cases, it’s safe to say the reader is learning something new. These guidelines will help you write clear, concise instructions, which will provide your reader with the best possible experience.

Basics

Do the hard work to make it simple.

Help the reader follow along. Break instructions or processes down into individual steps. Use short, simple sentences with words people use in everyday conversation.

Refer to navigation labels, buttons, and menus as they appear in the app or website. Verify the spelling and capitalization as you write. Be specific.

Instead of:

Open a new meeting invitation.

Use:

In Google Calendar, click Create.

Direct the reader.

Start your sentences with active verbs or clear objectives.

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 rather than what they can’t. (This is known as using positive language.)

Instead of:

You cannot continue without signing in.

Use:

Sign in to continue.

Guidelines

Titles and headings

Be consistent with how you phrase titles. If your guide or tutorial has several pages, stick to the same naming convention for scannability, such as:

  • Nouns: Policies, Teams, Offices
  • Verbs: Create an account, File a report, Download our data

Use sentence case for headings.

Introduction

Include a short two- or three-sentence summary about the document to help the reader confirm whether they’re in the right place, and improve search engine indexing.

Interface elements

Use clear verbs to tell readers how to interact with interface elements:

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

Tables

Tables are generally suitable only for data: two or more “objects” (rows) that share two or more “values” (columns). In tables, column widths are the same for all rows, which can make them easier to scan visually. Tables are easily navigable for sightless users so long as the content is organized in a logical way. Here are some other guidelines to consider:

  • When listing numbers, it’s good practice to align them to the right of their cell, with the same decimal precision (“40.50” and “1.00”) so that the numbers are easier to compare while scanning.
  • Always align column headings up with the values in the columns. For example, numeric column headings should be aligned right if the values are, too.

It’s rare that a document lives on its own. Tell people where to go for help if they have questions.

For documentation and guides, you might say:

For more information, see the Code of Conduct.

If your work relates to several other documents, pick the most important ones or gather the links in a section at the bottom.

indianaffairs.gov

An official website of the U.S. Department of the Interior

Looking for U.S. government information and services?
Visit USA.gov