Knowledge Base Standards

Article Content

The content of articles should be clear and concise. 

For consistency, titles should be written in the first person (e.g. I, me, my, etc.) and be in the form of a question, "How do I…", "When can I…", etc. or an action "Using…", "How to…", etc.
The first word and all proper nouns should be capitalized. Do not capitalize prepositions or conjunctions. Article titles should also address if the article applies to a specific application, operating system, or device (e.g. Windows, Mac, Android, etc.).

All articles must include labels – keywords that are related to the topic of the article. Labels help guide the search and group articles together.

Links

Linking to other Confluence Articles

If a topic needs further clarification and there is an article in our Knowledge Base that clarifies the topic, please include a link to the page and embed the link in the text you are writing (e.g. "Multi-Factor Authentication is another effective way to secure your ULID Account"). The link display text may need to change to better fit with your writing.
To insert these links,

1. Click the link icon in the toolbar at the top of the edit window.
2. Click Search.
3. Enter the name of the article you wish to link.
4. At the bottom of the window, you can edit the link text to change how the link appears.
5. Click Insert.

Linking to Websites Outside of Confluence

To link a webpage in your article, insert the link without http:// by altering the link text.
To insert these links,

1. Click the link icon in the toolbar at the top of the edit window.
2. Enter or copy and paste the link into the Address field.
3. At the bottom of the window, you can edit the link text if needed.
4. Click Insert.

A listing of ISU macros and how to use them are available in the Share Knowledge section of the Knowledge Base.
When using the Alert Macros, do not mix the suggested title such as, stating Warning under the Danger alert macro.

Formatting an Article

To support a cohesive look for the system and the information it provides, formatting must be consistent across KB articles. Articles must follow these guidelines in order to be approved for use on the IT Help web site.

Bolding

When you are instructing the reader to perform an action, bold the word that corresponds with the button/clickable element.

Italicizing

When you are referencing the title of an application, service, or window, italicize the title.

Quotation Marks

When instructing a reader to look for text on the screen, place quotations around the words they should be looking for.

Headings

Primary Headings: The primary headings in the article should be a Type 2 heading per the APA Style of formatting. Capitalize the first word and all proper nouns in the heading, but do not capitalize prepositions or conjunctions.

Secondary Headings: Secondary headings should be a Type 3 heading, per the APA Style of formatting. It should be used when you are creating new sections within a section of an article that is prefaced with a Primary Heading. Capitalize the first word and all proper nouns in the heading, but do not capitalize prepositions or conjunctions.

Tertiary Headings: Tertiary Headings will be a Type 4 heading, per the APA Style of formatting. While these are rarely used, they should be used when further detailing information within a Type 3 formatted section within your article. Capitalize the first word and all proper nouns in the sub-heading, but do not capitalize prepositions or conjunctions

Spacing

A double line break (i.e. one blank line) should be entered between paragraphs, and between pictures and text.

Numbering and Bullets

• Use numbers for steps.
• Use bullets when listing items that do not follow a certain order or when providing information.
• Use the numbered or bulleted list icon in the toolbar to apply; do not type in numbers or bullets.

Writing and Editing

Assuming User Knowledge

Assume the reader has basic technical knowledge. Instructions should be written such that faculty, staff, students, and annuitants at all levels of technical experience can follow along with minimal assistance.

General Writing Style Guidelines

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

Effective: Enter your ULID in the Username field.
Less Effective: ULID in the Username field.

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

Effective: Enter your ULID and Password to login.
Less Effective: Type user data at the login screen and click the OK button to login.

Use active voice to make instructions clear and direct.

Effective: The system displays the Print screen.
Less Effective: The Print screen is displayed by the system.

Use present tense to make text simple.

Effective: The system displays the Print screen.
Less Effective: The system will display the Print screen.

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

Effective: Enter your ULID and password.
Less Effective: Type the user's ULID and Password.

End each sentence with a period unless it could cause confusion about what to enter in a text field, in which case the period is not needed.

Effective: Select Connect to Server and type vnc://ComputerName.ad.ilstu.edu
Less Effective: Select Connect to Server and type vnc://ComputerName.ad.ilstu.edu.

If there are multiple ways to complete a task, provide the shortest, simplest way. Don't confuse the issue by providing multiple sets of steps. Note the use of > between the menu options.

Effective: Choose File > Save.
Not Effective: Choose File > Save or press Windows key S.

Writing Step-by-Step Instructions

Instructions should be written as a numbered list.

The audience for the instructions and any other requirements should be mentioned prior to listing the instructions. Information on what needs to be included in How-To articles can be found in the following article, How To Articles.
Each step should express a single action in the sequence of instructions and should not be overly complex. If a complex process needs to be completed, it should be broken down into simpler, more explicit steps.
Some steps may require users to enter content into multiple fields within a window or require additional instructions. In these cases, it is acceptable to enter this information as a second level bulleted list. Instructions should not go beyond the second level list.

Application windows or icons should have their names italicized (e.g. Google Chrome, Outlook, Documents, etc.).

Each step will usually begin with, and always contain, an action. The noun receiving the action should be bolded. Action words should be consistent within the instructions. A list of preferred action words and their uses are listed below.

Preferred Action Words or Terms:

• Check/Uncheck – For items where a check box needs to be selected.
• Choose – A menu option (e.g. Choose File > Print from the menu). Also note the use of > to separate menu options.
• Click – A button on the screen (e.g. Click OK).
• Double-click
• Drop-down menu
• Enter – Text must be typed into a field.
• Log in or log in to – The act of entering information to access a system or account. Note that login is a noun referring to a web page or part of a web page where a user would go to enter information to access a system.
• Open – An application or file.
• Press – A key or physical button (e.g. Press Windows key L to lock your computer).
• Right-click

Links

It may be helpful to add links to additional instructions or resources in the article content. For accessibility purposes, it is important the text of the link is descriptive of where the link goes, preferably the name of the linked page. Do not use links that say only "click here."

Effective: More information is available in Top Tech Tips for Students Learning and Attending Class Online.
Not Effective: More information is available here.

If the link goes to a file, include the file type as part of the link in parentheses.
When linking other knowledge articles, the text of the link should only contain the article title and no other information, including the article number.

Effective: Logging in to Office 365
Not Effective: 728: Logging in to Office 365

Images

Images may be used to assist the user in completing the task. For example, if more than three setting fields need to be changed in one window, include a screenshot of the final dialog box with all the settings completed. A screenshot would not be necessary for a step where the only action the user needs to take is click OK.
They should support the step they are associated with, generally a dialog box, menu, or applicable part of a window. It's not necessary to include a screenshot of the entire screen or application window, if the user only needs a selected area.
Images should contain alternative text so they are accessible to users of assistive technology such as screen readers.

Images must be a JPG/JPEG at 300px x 300px

*When added to a card, the rendered image will become circular.

Article Length 

Articles should be kept short and require minimal scrolling. If there are multiple sub-sections in the article and the article is long (scrolling required), add anchors to the subheadings to facilitate quick access to relevant information.

Macros

Macros are visuals and other actions that dynamically organize your content and allow you to draw attention to different aspects or content. These are useful for when you need specific information called out. Additionally, macros allow you to easily organize your content, create page anchors, and much more.

Articles created and viewed digitally must meet accessibility requirements to ensure the content can be utilized by those with assistive technology products. Information and guidance on creating Accessible Documentation is available.