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.
The title of your document should be clear and concise. It should fit the following format:
Title words are automatically included as keywords so there is no need for the author to include them.
Keywords should include:
You may also include:
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:
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.
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:
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.
|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.
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:
Examples of menu actions and commands in a sentence:
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.
This field is located under the expandable Show Additional Fields section found at the bottom of the document edit screen.