KB User's Guide - Documents Tab - Document Style Guidelines

When creating, reviewing, or editing a document please follow these guidelines.

Title

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), UW-Madison (UW-Madison only).
  
  
• 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: articles (a, an, the), coordinating conjunctions, (and, nor, or, for, but, etc.) nor do we capitalize prepositions that are fewer than five letters (on, at, to, from, by, etc.).

Keywords

Title words are automatically included as keywords so there is no need for the author to include them.

Keywords should include:

• product or service names
• key concepts
• error codes
• synonyms
• acronyms

You may also include:

• common misspellings (example: a user types in WISDOM but intends to search for a document on software called WISDM)
• former service names
• former product names
• former department names/ department acronyms
• other phrases describing similar action (example: transfer document ownership, reassign ownership, hand off, hand-off, hand over, turn over, give over, convey, impart, dispatch, pass on, advance, bestow, return)

Summary

Briefly describe the content in this field in one or two sentences so the reader knows what to expect. Depending on your content, you may write one or two of the points below:

• Start with an introductory sentence
• Convey the specific ideas
• Include the facts or key points covered
• Identify the main idea(s)
• Include source(s)
• Include a disclaimer
• Include contact information

The KB Summary field has no character limit. If you would like to apply formatting to the summary (example: bold, italics, code...), you may use HTML in the Summary field.

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:

• Accurate Content - Make sure all text and screenshots are accurate. During review make sure text and screenshots are still accurate. This includes making sure that all links work.
  
  
• Accessible Content - It is important to ensure that your content is fully accessible to all users, including but not limited to those who use assistive technology (e.g., screen readers). You can find information common accessibility considerations in KB User's Guide - General Info - How to Create Accessible Documents.
  
  An "Accessibility Checker" tool will run automatically when the Active status is selected, but it is also recommended that you periodically scan your document for any potential issues by running this tool manually. For more information on checking your document for accessibility issues, please see KB User's Guide - General Info - Checking KB Documents for Accessibility.
  
  
• Headings - Headings should be used to introduce new sections of documents. The Heading 2 (h2) heading is used to introduce major topics or sections, and the Heading 3 (h3) and Heading 4 (h4) headings are used to introduce subsections. Because the document title is displayed as a Heading 1 (h1), you should use only Heading 2 (h2), Heading 3 (h3), and Heading 4 (h4) heading sizes in your documents. You may leverage these headings to create an in-page table of contents.
  
  
• 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.
  
  
• KnowledgeBase - verify spelling of the word "KnowledgeBase". It should be spelled as one word; capital K, capital B.

• Spacing After Periods - Use a single space after periods. Double-spacing is no longer the standard for digital content.

• Images and Attachments - Images and other attachments (such as Word documents, PDF files, and video files) can be added to enhance or illustrate your document. Images should not be used in place of clear and concise instructions and explanations; they should, rather, emphasize your instructions. For guidelines on images, see KB User's Guide - Documents Tab - Image Guidelines.

• Using Bold, Italics, Underline, and Quotation Marks
  
  The following table has guidelines for using Bold, Italics, Underline, and "Quotations Marks":
  
  

  Formatting Conventions

  Convention	Usage guidelines	Examples
  Bold	To instruct a reader to actively do something on screen. To instruct a reader to press a key on the keyboard.	Click on Start. Press F1 on the computer keyboard.
  Italics	To denote text that a user will need to type. To cite special credits. Use of italics should be limited, as it may pose readability challenges to some users.	Type msconfig. Adapted from Apple KB.
  Underline	Using underlines is not recommended in order to avoid confusion with hyperlinks.
  "Quotation Marks"	To indicate error messages, screen prompts, or field names.	"Error: type 1". Fill in the "Host" field.

• Conventions - When documenting a series of buttons or items a user must click on, use the ">" (greater than) symbol to separate the items and bold the entire thing. For example, to tell a user to click on tools and then go to options, format it as such: Click on Tools > Options.

  • If you are composing content in HTML, please note that this symbol must be entered as > due to HTML standards.

• Use the word "Press" instead of the word "Hit" - Rather than instructing a user to "Hit Enter." say "Press Enter" and phrase the main method description in terms of what it does.
  
  Frequently used verbs in software documentation:

  • Click
  • Double-click
  • Select
  • Press
  • Get
  • List
  • Create
  • Search

  Examples of menu actions and commands in a sentence:

  • On the File menu, click Open.
  • Type a name in the User Name field.
  • In the Open dialog box, click Save.
  • On the computer keyboard, press Enter.

• Check Links - When authoring docs be sure that all links work. When reviewing docs, be sure all links work. At every six month review, be sure to double check that the links still work. The KB has a broken link checking feature, for more information, see KB User's Guide - Documents Tab - Identifying Broken Hyperlinks on your KB documents .

• Lists - Ordered and Unordered - either all items should end in a period or none. It may depend on whether or not the information is more like a sentence or a list of phrases. Be sure to make it consistent for any given list. Use Ordered Lists for step by step directions and Unordered Lists for a list of related items.

• Mobile View - Test documents on mobile device to check formatting. Alternatively, most browsers have an "Inspect" feature that will include an option to emulate a mobile device for testing.

• Browsers - Occasionally spot check documents on something other than your preferred browser.

• Copying & pasting content from Microsoft Word or Google Docs - Copying content from either place often brings extraneous code that, in time, nests and becomes unmanageable. When you past content from one of these sources into the TinyMCE editor, you will be prompted to keep or remove formatting. It is recommended that you opt to remove formatting when pasting and re-apply it with the editor as needed.

See Also:

• KB User's Guide - Documents Tab - Image Guidelines