Standard: KM / Style guide for KB content contributors

Standard

  • Documentation standard for the development of Knowledge content

User

  • Subject-matter Expert
  • KB Contributor

Environment

  • 55923: Knowledge Management Process
  • 348532: Knowledge Base (KB)
  • 56345: Knowledge Management (KM 2.0)

Style Guide 

  • Do not create duplicates. Search for existing Knowledge before you contribute new Knowledge. If a duplicate exists, it may indicate that the original Knowledge article needs to be modified to enhance search results
  • Maintain an appropriate context (words) that will make sense to your reader (the user)
  • Remember your reader (the user). Your resolution must contain all the appropriate Knowledge required by your reader. Be clear and concise. Choose terminology carefully. Provide the appropriate level of direction. Write to your reader as if you were talking to them over the phone
  • Do not reference a user or an incident. Focus on the objective and the resolution/answer. Articles should not be user/installation-specific, i.e., node name or internal system
  • List procedural steps in proper order
  • Use our approved list of names and terminology when referring to applications, products, services, etc. Consistency is created when all articles are associated with the same product name
  • Spell out a term at first reference, and follow it with the appropriate acronym in parentheses
    • Example: Knowledge Base (KB)
  • Use all-caps for acronyms and error codes. Capitalize the first letter of menu options, product names (unless approved list indicates otherwise), new sentences, and words as they appear in apps
  • Write instructions in a gender-neutral, active voice
  • Use the DD/MM/YY format for dates
  • Do not use graphics, images, tables or content attachments, unless you know how to format to accessibility standards  
  • Do not use descriptions that rely only on sight (e.g., “click on the square,” “the box on the left side of the page,” “the big blue text”)
  • Do not use abbreviations
  • Italicize button names, menu items, and file names. Bold any text that the user is instructed to enter/type
  • Use the '+' character when instructing the user to press multiple keys at the same time. Use commas for sequences
    • Examples: CTRL+ALT+DEL; Press Alt, F, and X
  • Use hyphens when two or more words are used together as an adjective, but not with words beginning with prefixes 
    • Examples: double-click, uncheck
  • Be consistent with instructions
    • Examples: Click the Submit button; double-click the icon
  • Reference your source at the end of procedural instructions
    • Example: macOS Sierra reference guide, page 10
  • And use spell-check!

 

Note

 

Print Article