sections in the article
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
DO NOT WRITE
To Install the Connector
Follow these steps to install the connector:
1.Download the .zip file that is attached to this article.
2.To upload the .zip file to inriver, go to inriver Control Center > Connect > Packages.
3.Select which extensions to install from the uploaded file by going to inriver Control Center > Connect > Extensions.
4.Click Add extension and enter the details for each Listener (see information below).
5.In the Extension settings, click Get Default Settings. Go to section Configure the Connector in this article for detailed information about each setting.
6.Once the settings have been updated, click Reload Service Settings to enable the new settings.
Install the Connector
The connector is easily installed by following these basic steps:
1.Download the compiled ZIP package (attached to this article)
2.Upload the ZIP to your instance of inriver via the menu inriver Control Center > Connect > Packages
3.Now you need to select which extensions to install from the uploaded package. Do this by going to menu inriver Control Center > Connect > Extensions
4.Click “add extension” and enter Details as seen for each Listener below.
5.Go into Settings on the Extension and click "Get Default Settings". Details about each setting in the chapter below "Configure the Connector".
6.After settings has been updated, make sure to click "Reload Service Settings" for the new values to activate.
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.
DO NOT WRITE
|Accessing the Web Portal||How Do I Get Access to the Web Portal?|
|Using Queries||Query usage|
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.
DO NOT WRITE
|This article describes how to download, install, and use the inriver schema-based outbound connector.||The inriver schema-based outbound connector is used to output data as XML and can also export media files.|
|To get more information about how to create and save a work area, see the videos below.||See the videos below!|
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.
DO NOT WRITE
|Deleting a work area||How to delete a Workarea that you don’t need anymore|
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.
Have a look at Microsoft’s excellent Style Guide:
Please sign in to leave a comment.