Knowledgebase, Article Content Standards

KnowledgeBase content must be in compliance with the guidelines described by this document, as well as the Style Guide for Technology Services and the Illinois Brand Guidelines. Documents that do not sufficiently meet these will be returned to their author for revisions prior to publication.

Title

  • Titles should use the following naming convention: Service Name, Service Offering Name, Description of Article
    • Exceptions may apply for articles describing multiple service offerings.
    • Use short descriptions; one line maximum.
    • Do not write complete sentences for titles.
  • Service names should match the names used in the Service Catalog.
  • Follow AP style for capitalization and punctuation. See the Office of the CIO Style Guide for guidance. 
  • Do not use CSS to alter the appearance of text in the title. The title will always render as an h1 element which should not be modified.
  • Use present-tense verbs.

For example: Microsoft Teams, Scheduling a Meeting
Instead of: How do I schedule a meeting with Microsoft Teams?

Summary

  • Use the Summary field to provide introductory information about the service or document, rather than putting this information in the Body.
  • Provide a brief synopsis of the document’s content in a few sentences.
  • Do not format the summary as a question, or start with phrases like “this page contains” or “this page links to”. Do not tell the reader what you will tell them, simply tell it to them.
  • Do not use code to alter the appearance of text in the summary field.

Keywords

  • Include any terms a user might search for when they need the information in the document.
  • Keywords are not case-sensitive; “Pear” and “PEAR” and “pear” are redundant.

Keywords to include:

  • Alternate product/service names, nicknames, and former names
  • Main concepts
  • Acronyms and abbreviations
  • Codes or messages from errors addressed in the document
  • Other verb tenses, action words, or plurals of other keywords or words in the title
  • Common misspellings of other keywords or words in the title

Article Body

Text Formatting

  • Follow the Office of the CIO Style Guide.
  • Use Paragraph, the default format for text in the editor, for all normal text.
    • Avoid using custom styling to change the appearance of text.
    • CSS can change colors and fonts, but incorrect use of these features is known to cause formatting problems and difficulty for readers with low vision.
  • Use bold to indicate the name or text of a button or key a user must locate, and use italics to indicate text a user will need to type.
    For example: “Type msconfig, then press Enter.”
  • Do not use underlined text, as it can cause confusion with hyperlinks.
  • Do not use highlighted text, as it is not reliably accessible or aesthetically consistent.
  • Do not directly copy-paste text from a Word document.
    • Word includes XML formatting data when copying which can cause code issues in the KB editor.
    • Paste text into a Notepad note and then copy it into the editor or use a site like HTML Tidy to inspect and ‘clean’ pasted text.
  • Use a single space after periods.
  • If attention needs to be drawn to a specific section of a page or block of text, do not make that text larger and bold. Instead, surround it in a colored background.
    Example code that accomplishes this:
    <div style="border-style: solid; border-color: #ff5f05; background-color: #ffcc99; padding: 11px; margin: 5px;"><p>Styled sections like this will be made easier in the future, stay tuned!</p></div>

    Styled sections like this will be made easier in the future, stay tuned!

  • Use the built-in TinyMCE Accessibility Check iconTinyMCE Accessibility Checker tool. It runs automatically when documents are submitted, and highlights and helps repair common web accessibility issues.

Writing Style

  • Consider your audience:
    • External articles should be written to be read by someone with minimal experience, and avoid jargon and overly technical terminology.
    • Internal articles or pages intended for IT workers can be more technical in nature and expect a baseline understanding from the reader.
  • Use a mix of second and third person grammatical points of view.
    • Instructions can use “you” to refer to actions the reader will take.
    • Do not refer to “clients”, “customers”, or “they” and “them” in external articles.
    • For example: "The site will ask you to log in. Use your Illinois email address and password."
  • Use bullet points, numbered steps, or screenshots rather than long blocks of text. Keep paragraphs to a few short sentences.

Headings

  • Use the editor’s preset heading formats.
    • Main section titles should be Heading 2
    • Subsection titles should be Heading 3
  • Heading 1 is the default for all document titles; do not use it in body text.
  • Headings exist to divide the page into sections, not to emphasize text.

Bulleted and Numbered Lists

  • Use the editor’s buttons to insert lists (rather than creating them by hand).
    • The editor keeps numbering, formatting, and HTML code consistent when these buttons are used.
  • Use numbered lists for sequential instructions.
  • Use bulleted lists for related but non-sequential pieces of information.
  • Only use lists when they contain three or more items.

Links

  • To link to another KnowledgeBase document, use the Insert/edit KB link doc (document with chain) button or the See Also field.
  • To link to other websites, use the Insert/edit link (chain links) button.
    • Text to display should be the linked page’s entire URL or title.
    • Use descriptive text for links rather than just “click here” or similar.

Images and Screenshots

  • Use a screenshot when the reader needs to locate something on their screen (an icon, button, tab, etc.).
  • Only use screenshots when necessary to avoid visual clutter.
  • For images showing a specific message or prompt, also include its exact wording in text.

Alternative Text

  • Images must have 'alt text' set for screen readers to understand them. The image insertion dialogue includes an Alternative description field to set this.
  • Make alt text descriptive of what the image shows, to fully replaces the image if it cannot be seen or loaded.
  • Decorative images (those that do not contribute to the document's content) do not need alt text. This can also be indicated in the image insertion dialogue.

Videos

  • Use Illinois Media Space (Kaltura) to host videos.
  • Use playable embeds rather than links out to other sites.
  • Include a brief description of the video’s content.

Collapsible Panels

  • Use the Insert/edit collapsible panel button in the editor to add an animated panel that expands and contracts to dynamically show and hide sections of article content with a click.
  • This is an optional feature and should be used sparingly. Consider breaking up articles with many sections and subsections into separate documents.
  • Do not nest these panels inside one another.
  • When using more than one panel, have one be expanded by default and the rest collapsed.

Security

  • Do not include any information protected by HIPAA, FERPA, or similar regulations in any document content.
  • Edit screenshots to hide individual account information.
  • Check that access control settings are working as intended.
  • Do not include contact or location information of individual employees; prefer resource accounts when providing a point of contact.
  • Some articles contain a mix of information intended for the public and information intended only for Technology Services. Internal-only information should be contained in an internal block div, created from the padlock icon in the editor. Include a horizontal line to visually separate these sections.
    For example: an article describing a service also needs to include information for Help Desk consultants escalating tickets to that service team. The article is external, but has an internal section with a horizontal rule and “Help Desk Internal Notes” heading that cannot be seen by external users.


Keywords:
KB, review, tier 2, request activation, new, author, ACS 
Doc ID:
80382
Owned by:
KnowledgeBase A. in University of Illinois Technology Services
Created:
2018-02-22
Updated:
2024-11-22
Sites:
University of Illinois Technology Services