Knowledge Base: Style Guidelines
This style guide lists a set of standards for design and writing of KB documents.
When creating, reviewing, or editing a document please follow the KnowledgeBase Style guidelines. These guidelines are recommended to ensure that all documents use the same style and format and help provide consistency for all users.
Titles
The title of your document should be clear and concise. It should fit the following format:
Product Name (Restrictions): Descriptive Title
- Product Name - The name of the product, application or service.
- (Restrictions) - Any restrictions that apply to the document should go between the parentheses. Examples of restrictions are problems that affect only Macs (Mac), Windows (Win)
- Descriptive Title - A short description of the document's main theme. Capitalize the first, last and any important words in a title, which is known as Title Case. Generally, we do not capitalize the following: a, an, the, and, or, for, but, etc.
Example: OneDrive for Business (Mac): Sharing files
Keywords
Keywords should include product or service names, key concepts, error codes, synonyms, and acronyms. Title words are automatically included so there is no need to manually include them. You may also include common misspellings
Example: a user types in WISDOM but intends to search for a document on WISDM
Body
The body contains in-depth information about a product, service or guides users through a series of detailed instructions or troubleshooting steps. The body section should use the following format guidelines:
Headers
One of the best ways to assist readers is to use well-organized headings and subheadings. Headers should be used to introduce new sections of documents. The Header 2 is used to introduce major topics or sections, and Headers 3 and 4 are used to introduce subsections. Use headers rather than bolded text.
Important: Keep headings sequential and don't skip a heading level.
Numbered Lists
Use numbered lists for step-by-step directions. (Be consistent when including a period. If it is a sentence, place a period at the end.)
Tip: Use Alt + Enter to add a space between items in a numbered or bulleted list.
Bulleted Lists
Use bulleted lists for a list of related items. (Be consistent when including a period. If it is a sentence, place a period at the end.)
Order of Instructions
Write in a logical order. Write the instructions in the order that the user will go through.
Example: On the File Menu, click Save.
Not: "Click Save on the File Menu"
Grammar and Spelling
Accurate spelling and grammar are very important. Make sure to proofread documents after they are completed. Use the spell check option on the toolbar.
Terminology
When writing about a program, use the correct terminology given by its developers. For example, when referring to the Microsoft Office toolbar, use the word "Ribbon". Frequently used verbs in software documentation:
- Click
- Double-click
- Select vs. Highlight (Only use highlight when referring the highlighter tool)
- Type
- Press
- Settings
- Options
- Drop-Down
Links
When authoring docs be sure that all links work. When reviewing docs be sure all links work. When reviewed, be sure to double check that the links still work.
Text formatting
Bold Text
When writing or editing instructions, bold the words or buttons that readers will click on or interact with (a link, a dropdown, etc). Be consistent throughout the article.
Example: Click Start, point to All Programs, point to Microsoft Office, and then click Microsoft Office Word 2016.
Example: Click Start > All Programs > Microsoft Office > Microsoft Office Word 2016.
Italicized Text
Italicize text that the reader will type.
Example: To access the UW-Stout website, type www.uwstout.edu
Italicize names of windows or dialog boxes.
Example: The My Computer window opens.
Keyboard Keys
Capitalize the titles of keys on the keyboard. Keys that should be pressed simultaneously should be combined with a + sign.
Example: Press CTRL+ALT+DELETE to log in.
Quotation Marks
Use quotation marks to indicate error messages, screen prompts, or field names.
Example: "Error: type 1"
Example: Fill in the "Name" field.
Images and Attachments
Images often make a page easier to read and understand. However, if your image is too big, too small, not aligned properly, or fades into the page, it will only hinder the page's information.
Attempt to keep images no larger than 500 pixels in width. Large images obscure text and take over the page. Very small images (especially with text) are difficult to read and take up space without providing useful information.
Include a line space between text and an image to make sure the text is easier to read. (Shift + Enter)
Highlight areas on a screenshot using a call-out box. Use a simple red box to highlight a bottom or area on an image.
Example: 
Do not include images with text directions, unless the directions are also spelled out in the document. Screen readers can not read the images on an image.
Always include Alt Text that clearly describes what the picture is demonstrating.
Tip: Use Paint 2D or other editor to add call-out boxes.