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

This style guide lists a set of standards for design and writing of KB documents. This document defines the standards and conventions used in KB User's Guide Documents. These guidelines are provided to ensure that all documents use the same style, format, and HTML standards. Consistency in documentation makes it easier for users to utilize the KnowledgeBase.

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), UMMC (Main Campus 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

Keywords should include product or service names, key concepts, error codes, synonyms, and acronyms. Title words are automatically included so there is no need for the doc writer to include them. You may also include common misspellings (example: a user types in iCare but the actual name of the application is Safety Intelligence).

Summary

A good summary succinctly indicates the purpose and/or the main point or issue of the entire document so that a user may glance at the opening paragraph and quickly see what is available in that document. We encourage you to leave the Summary field as simple as possible. Do NOT copy your summary into the Body as it will create a duplication in the document. 

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 - Headers should be used to introduce new sections of documents. The h3 header is used to introduce major topics or sections, and the h4 header is used to introduce subsections. Use only h3 and h4 header sizes in your documents.

  • Font - Use the same font (Arial or Times New Roman) throughout your documents. 

  • Font size Use size 3 throughout your documents. 

  • Alignment - Align your content to the left. Avoid aligning your content to the center or the right side. .  

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

  • 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 - Do NOT double-space after periods. It is no longer the standard and it doesn't show up any differently than single spacing after periods due to HTML standards.

  • 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":

    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.
    Type msconfig.
    Adapted from Apple KB.
    Underline Make minimal use of underlines 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 > (it must be entered as > due to HTML standards) 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.

  • Use "Press" instead of "Hit" - Rather than instructing a user to "Hit Enter." say "Press Enter."
    Frequently used verbs in software documentation:
    • Click
    • Double-click
    • Select
    • Type
    • Press

    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.

  • 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 Site - Test documents on mobile device or use mobile view / full view toggle from PC or Laptop to check mobile formatting. Click here for more info on mobile view.

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

Dropdown Menus

These menus should all be filled out correctly. If you do not know what to choose for a menu, please indicate that in a comment to the document. For information on the dropdown menu fields, see KB User's Guide - Overview of Fields in Document editor

JavaScript/CSS

This field is located under the expandable Show Additional Fields section found at the bottom of the document edit screen.

Instead of placing JavaScript or CSS in the body of the document, where, in time, it may be difficult to edit among your regular content, you can place it in its own distinct field.

Now, when the document is rendered, the content in the body is rendered first, followed by the any JavaScript or CSS content. This way the functionality of the JavaScript/or CSS is preserved without causing problems when editing.

See Also:




Keywords:kb knowledgebase knowledge base users guide document guidelines guideline style guide style manual   Doc ID:68536
Owner:Judy G.Group:University of Mississippi Medical Center
Created:2016-11-09 13:53 CSTUpdated:2016-11-09 14:37 CST
Sites:University of Mississippi Medical Center
Feedback:  1   0