Guidelines for Writing Knowledge Base Articles

Overview

Use this document as a reference for the style guidelines when writing and editing knowledge articles. A style guide is essential for consistency and professionalism in communication. It maintains brand identity and accessibility guidelines, making content inclusive and user-friendly for all. For more information or help regarding accessibility and articles please reach out to eLearning. 

Style Guidelines

1. Title/Subject
   • The title should be action based. Users tend to look for articles when they want to accomplish a task.
   • If the title is not a question, all words that are four or more letters should be capitalized. 
   • Titles should be brief. Use tags to expand on the topic for search ability. 
2. Headings
   • The title is automatically saved as Heading 1.
   • Use Heading 2 for your first topic, Heading 3 for subtopic, etc.
   • Select Headings under the Format drop-down menu. 
   • Text that is not a list or a heading should be formatted as Normal. 
3. Font Style and Font Size
   • Do not adjust the font style or font size. A readable font and size for most users has already been selected.
4. Overview Statement
   • Create a brief overview that explains the purpose of the article. 
   • Consider your audience in your word choice. 
5. Step by Step Instructions
   • Articles should be written with the assumption that the user has no prior knowledge or experience.For example, for ctcLink articles, Step 1 would be Log into ctcLink at https://gateway.ctclink.us.
6. Tone
   • Articles should be written in present tense, active voice and 2nd person (you, your). 
   • Use basic language and stick to the point so that users can resolve the issue as quickly as possible.
7. Spacing
   • At the end of a sentence use single space, not double space. 
8. Hyperlinks
   • Hyperlinks are an embedded link to another webpage. 
   • Hyperlinks should be descriptive text, which provide users with the proper context of where clicking the link will take them. Do not use click here. 
   • Set Hyperlinks to open in a new window.
9. Images
   • All Images should have Alternative Text (Alt text). Alt text is a written description of an image that appears on a webpage. This can be used for accessibility reason, such as screen readers. 
   • The Web Accessibility Initiative has resources on how to create alt text.  
   • Images in relation to lists or steps should be inserted after the text or step.
   • Images need to be large enough to be clear. If there is text in the image it should at least be a similar size to the text in the article. 
   • Use the built in image uploader. 
10. Bold, underline, ALL CAPS, quotation marks, and italics.
    • Use Bold to emphasize important steps, instead of underline, ALL CAPS, "quotation marks," or italics.
    • Never underline. The use of underlines can create the illusion of a hyperlink.
    • ALL CAPS should be used very sparingly. Only in cases as secondary emphasis only when additional emphasis is needed within the same article. Ex: Allow all individuals to view this article EXCEPT the associated groups below. CAPS are used here to add additional emphasis.
11. Acronyms
    • If you will be using acronyms, the first time you write it, be sure to include the entire name with the acronym in parenthesis. Example: The API (Application Program Interface) dictates...
12. Latin Abbreviations 
    • Do not use Latin Abbreviations such as i.e. and e.g. Instead, use in other words, to put it differently, for instance, for example, or such as.
13. Lists
    • Bulleted lists should be used to increase the ability to scan the article efficiently and find what is needed quickly.
    • Use bulleted lists in most use cases. Numbered lists often break. 
    • Lists should never be created using manual typing, use the text formatting.  
    • Be sure to maintain consistency. For example, if the first item is a full sentence, write the rest of the items in that list the same way.
    • Only use periods at the end of a bulleted list item when it is a full sentence or completes a sentence stem.
    • Capitalize the first letter of the first word of bulleted and numbered lists.
14. Capitalization
    • Capitalize the following
      • The first word of a complete sentence following a colon
      • Keyboard shortcuts Capitalize the first letter of a keyboard shortcut or combination of shortcuts. Ctrl + Shift + C
      • The name of a key on the keyboard
      • The first word in numbered or bulleted lists
      • The letters of abbreviations and acronyms unless they are normally lowercase
      • The first word of a complete sentence
      • Proper nouns and names, including brand names, product names and feature names
15. Consistency
    • Be sure to maintain consistency in your steps. Choose one description and use it continuously throughout your articles. For example, do you use click or press or select?
16. Common Misspellings and Misuse of Words
    • Plugins does not have a hyphen.
    • Add-ons does have a hyphen.
    • Website is one word.
    • Web page is two words.
    • Home page is two words.
    • Use email instead of e-mail.
    • The Internet is uppercase.
    • Log in and log out are verbs. Example: Log in to the website. The same applies to sign in and sign out. Do not use log into or  sign into.
    • Login and logout are nouns or adjectives. Example: Click the login button.
    • When writing numbers small numbers ranging from one to nine should be spelled out. Ten and above are written as numerals except at the beginning of a sentence.
17. Tables
    • Tables are not accessible for screen readers, please avoid them whenever possible. 
    • Tables should not be sued for formatting. 

Additional Resources

For more information, view Accessibility Standards and Guidelines.