Interface writing
We often write technical documentation where it's safe to say the reader is learning something new or troubleshooting. Write clear, concise instructions to provide the best possible experience to the user.
Basics
Do the hard work to make it simple for the user
Help the user follow along. Break instructions and processes down into individual steps. Use short, simple sentences with words the user will recognize and understand.
Refer to navigation labels, buttons, and menus as they appear in the app. Verify the spelling and capitalization as you write. Users look for the same name as in the instruction. Always boldface interface items and omit any terminal punctuation from the bold.
Be specific and give the reader as much help as you can.
Instead of:
Open a new support ticket.
Use:
Click Help > Contact Technical Support.
Direct the reader
Use active verbs and clear objectives.
Instead of:
We can help you if you create a JIRA Service Desk request.
Use:
Click JIRA Service Desk to create a help request. Include details about your problem.
Or:
To get started, click the JIRA Service Desk link to create a new ticket. Remember to include the details of your problem.
Us positive language and focus on what the reader can do rather than what they can't do.
Instead of:
You cannot submit without answering all queries.
Use:
Answer any open queries and then submit the proof.
Guidelines
Titles and headings
Use consistent naming by sticking to the same naming convention. This makes it easier for the reader to scan and find what she's looking for. For examples:
- Nouns -- Proofs, Users, Task
- Verbs -- Create an account, Print a report, Submit a proof
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 also to improve searchability.
Interface elements
Use clear verbs to tell readers how to interact with interface elements:
Choose from drop-down menus.
Select or clear checkboxes and radio buttons.
Click or tap buttons.
Follow or open links.
Bold interface names and choices:
- Click File > Open. Word displays the File dialog box.
- Select a file.
- Click OK.
Always use the spelling, grammar, and exact names seen in the interface element, even if they are grammatically incorect.
User input
Use italic to distinguish user input from plain text. For example,
Type the exact name of the dialog box, such as Exit system.
Command line items
Command line items should be in monospace, such as Courier, Consolas, or similar. Do not use italic for this form of user input.
At the C: prompt, type the following: chkdsk /v /f
and press Enter.