Editor guidelines

Creating content in SelfGuide is intuitive and efficient process, but it is important to create instructions in an uniform approach. Based on experience and feedback this document is created to support organizations and editors with findings and guidelines that will support them while creating Instructions, User Guides and Courses. The goal of this article is to minimize the difference between created content by different editors.

Instruction properties

Every instruction within SelfGuide is composed of different properties. These properties are the base of the instruction and have a big impact on how organizations disclose content to its employees.

Title:
First mention the ‘action’ (first letter is upper case), and after this the ‘subject’. For example: ‘Create graph’. Do not use any articles within the title (Not ‘the calculator’, but ‘calculator’). So, if an instruction is beind made about creating a new Team in Microsoft Teams, the title should be: ‘Create a new Team’.

Description:
The description should be short but powerful. Think about how peopel search for instructions, what terms do will they use during the search? Try to adapt the description to these insights.

Tags:
The amount of different tags that are used should be limited. Tags should help an editor to group instructions according to their topic, department or role within the organization. If editors use to many tags it becomes unclear and the tags lose their purpose. An advice is to only create tags in agreement with other editors.

Applications:
Only select the applications that are used within the instruction. If an application does not yet exist within SelfGuide, editors shoud have an agreement about adding new applications. If a new application needs to be added to SelfGuide, send a request to support@selfguide.com.

The instruction

First step:
If there are multiple actions that are being described within the same screen, an instruction should start at how someone reaches this part or program. For example: changing different settings within the settings tab of Microsoft Teams. This start by first showing how someone gets to the settings tab.

If the steps that are required to get to the part or program are more than three, another instruction should be created, which indicates how to get to the settings part, instead of doing it in every instruction.

Last step:
The ending of an instruction is the result of the specific action which is performed. The result of an instruction can be shown, by adding an additional step and hiding the step action. For example: the last stop of the instruction ‘Create graph’ should be a step which contains the actual graph. This step can be called ‘Result’.

Step title:
The name of a step within an instruction should be brief, preferably one or two words. The step title should never be empty and has to be filled. The first letter of the first word should be upper case. If the title reflects text that can be seen on the screen, it should be written in the same way.

Annotation:
More than one annotations are accepted. The first annotation should reflect the action within the step. The second annotation should be added to give additional information if needed. An annotation should be placed close to the location of the mouseclick, but it should not located over the clicking location.  

When using annotations one should think about the tone of voice (how we talk to the reader):

• Target audience: For whom is this instruction created? What is their educational level? How experienced are they with this topic? These are all questions that should be asked while creating instructions.
• Language: All text is in English with an informal word usage commonly used.
• Writing style: Use an expository writing style to give inspiration, to motivate, to explain; Don't be directive or persuasive.

Another aspect that should be taken into account is the formatting of text:

• Bold: Use bold to describe a function on the screen that can be selected. For example: To select the tab file in Word, you type: ‘Click on File.’.
• Italic: Use italic if some text has to be filled in exactly like in the instruction. For example: ‘Type the name John Doe.’.
• Underline: Use underline if something needs to be emphasized. For example: ‘Do not select this field.’.
• Single quotation mark: Use a single quotation mark to refer to a filename or the name of a folder. For example: ‘You can find all unread mails in the ‘Inbox’.’.
• Double quotation mark: Only use double quotation marks when a quote is stated.

Censoring:
Use censoring to hide names, e-mail addresses, and other sensitive company information. Censor the entire area that needs to be censored, or just censor small parts of it, both are allowed. Something that might be useful is creating fictitious accounts, which are used to create instructions.