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

• 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 CSS to alter the appearance of text in the summary field.

• The KnowledgeBase’s search function looks at document titles first, then for 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

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

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