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:  Skype 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 3 is used to introduce major topics or sections, and the Header 4 is used to introduce subsections. 

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.)

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. Most major browsers have a built-in spell checker. Use that to verify correct spelling.

Terminology

When writing about a program, use the correct terminology given by its developers. For example, when referring to the Microsoft Office 2007 and 2010 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

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.

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:  Example of a red call-out box on a screenshot




Keywords:articles, style KnowledgeBase KB Knowledge Base   Doc ID:88035
Owner:Heidi C.Group:UW Stout
Created:2018-11-28 13:43 CSTUpdated:2018-11-28 15:38 CST
Sites:UW Stout
Feedback:  0   0