Writing step-by-step instructions

What ss a how-to article?

How-to articles are short and answer a single question, for example

• How to Create a CVL
• How to Delete a Work Area
• How to Set Up a Channel Node

How-to articles focus on regular users, not developers

• No jargon, no techy language

How-to articles usually consist of a summary, followed by step-by-step instructions

How to write step-by-step instructions

Step-by-step instructions should be easy to follow:

• Instructions with more than one step should be numbered. Use a bullet if there is only one step.
• Don’t add too much information in each step.
• If there are several ways of doing something, focus on the most commonly used scenario.
• Refer to the user as you and to inriver as we.
• Start each step with an action verb, for example, click, go to, or open.
• Capitalize the first letter of a UI reference and write the UI reference in bold, to make it stand out.
• Start instruction titles with To + Verb, for example, ‘To Use an Extension’.
• End each instruction step with a period.
• If needed, use screenshots for clarification.

Good and bad examples: step-by-step instructions

Article title

The title should be a summary of the whole article. Keep it short and make sure it contains keywords that are relevant to the article content. This makes the information consistent and easy to find in the inriver Community.

Titles should capture the words and phrases your target audience would use, while avoiding jargon. Use a verb in -ing form to phrase your title.

Body text

Keep the information in the article body text simple and easy to follow.

Summarize the question you want to answer in the first sentence(s) of the article, then go into detail.

• Use This article is about… to direct the user to the article summary.

Use two levels of headings, H2 and H3, to improve article readability.

• H2 headings are clickable and provide an overview at the start of a long article.
• Keep headings as short, crisp, and clear as possible.
• Avoid using italics or bold in titles.

Break large paragraphs into smaller chunks of 1-2 lines to make it easier to get an overview.

General writing style

Write in complete sentences, including a subject, verb, and object.

Use simple language, omit non-essential words, and avoid technical jargon.

Use active voice to make instructions clear and direct.

Use present tense to make the text simple.

Address the user in the second person (you, your) to make it clear who must complete the action.

Introduce a bullet list with a sentence or fragment ending with a colon:

• Begin each entry with a capital letter.
• End sentences longer than three words with a full stop.
• Make entries in a list parallel: all items in the list must have the same grammatical construction.

Write UI items, feature or application names with initial capital letter in running text. Make sure that the term reflects the exact way of writing in the UI (capitalization and space).

Write out inriver-domain-specific terms in italics every time they appear in an article.

Further reading

Have a look at Microsoft’s excellent Style Guide: 

https://docs.microsoft.com/en-us/style-guide/welcome/