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 concise descriptions; one line maximum.
• Use phrases rather than complete sentences.
• Use service and offering names that match the Service Catalog.
• Do not use code to alter the appearance of text in the title.
• Use present-tense verbs.

Example:

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

Write a brief synopsis of the document's content in a few sentences.

• Use the Summary field to introduce the service or document. Avoid including this information in the Body.
• Do not format the summary as a question, or start with phrases like “this page contains” or “this page links to”. Simply state the key information directly.
• Avoid using code to alter the appearance of text in the Summary field.

The KB's search function relies on matching keywords (in addition to titles and body texts).

• Keywords should be separated by spaces; no punctuation is necessary.
• 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
• Popup messages or error codes from problems 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

Maintain a consistent user experience by formatting text uniformly across all KB documents. In most cases, this should be done using the default formatting settings. 

• Select and use preset text styles from the editor's drop-down menu.
  
  • Use "Paragraph" (the default setting) for all standard text.
  • Use heading levels to provide structure to the document. 
  • Avoid using custom styling to change the appearance of text.
  • Do not use CSS to adjust colors or fonts, as this can cause formatting issues and accessibility problems. 
• Use bold to indicate the name or text of a button or key the reader must locate, and use italics to indicate text that needs to be typed. For example: “Type msconfig, then press Enter.”
• Let the editor handle hyperlink colors and underlining. Avoid using underlines elsewhere to prevent confusion. 
• Do not use highlighted text, as it effects accessibility and consistent formatting. 
• Do not copy-paste text directly from Microsoft Word, as it contains XML data that can cause issues in the KB editor. Instead, paste text into Notepad then into the editor, or a site like HTML Tidy to inspect and clean text before pasting.
• Use a single space after periods.
• To draw attention to a specific section of a page or block of text, avoid using larger and bold text. Instead, use a colored background for emphasis. 
  
  • A predefined CSS class "orangecallout" can be used for this purpose:
    <div class=”orangecallout”><p>Since it is wrapped in an orangecallout div, this paragraph will be placed in a colored and bordered text box.</p></div>
    

    Since it is wrapped in an orangecallout div, this paragraph will be placed in a colored and bordered text box.

• Use the built-in TinyMCE Accessibility Checker tool. It runs automatically when documents are submitted, highlighting and helping to repair common web accessibility issues.

Writing Style

Know your audience:

• External articles are for readers with minimal experience, so avoid jargon and overly technical terminology.
• When referring to IT groups in external articles, use the appropriate organizational name (Technology Services or Office of the CIO) instead of specific team names.
• Internal articles intended for IT staff can use more technical language, assuming a baseline understanding from the reader.
• Use a mix of second person (you) and third person grammatical points of view. For example: "The site will ask you to log in. Use your Illinois email address and password."
  
  • Do not refer to users as “clients”, “customers”, “they” or “them” in external articles.
• Use bullet points, numbered steps, or screenshots to improve readability. 
• Keep paragraphs concise - just a few short sentences. Avoid long blocks of text. 

Headings

Structure the document by using the editor’s preset heading formats.

• Use Heading 2 for main section titles.
• Use Heading 3 for subsection titles. 
• Heading 1 is the default for all document titles; do not use it in body text. 
• Do not use headings to emphasize text.

Bulleted and Numbered Lists

Use lists to organize related information or outline steps in a process. They improve readability and break up large blocks of text.

• Use the editor’s list buttons instead of manually creating lists.  This ensures consistent numbering, formatting, and HRML code.
• Use numbered lists for sequential steps.
• Use bulleted lists for related but non-sequential 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.
  • Display the full URL or the page title.
  • Use descriptive text instead of generic text like “click here.”

Images and Screenshots

Screenshots help users know where to look for something, such as an icon, button, or tab. 

• To avoid visual clutter, only use screenshots when necessary.
• For images showing a specific message or prompt, include its exact wording in text.

Alternative Text (Alt Text)

• Alt Text ensures images are accessible to screen readers. Use the Alternative description field in the image insertion dialog to add alt text.
• Describe the image accurately and fully so users understand its content without seeing it. 
• Decorative images (those that do not contribute to the document's content) do not need alt text. Mark them as decorative in the image settings. 

Videos

Illinois Media Space (Kaltura) is the recommended video hosting platform for hosting videos in the KnowledgeBase. 

• Use playable embeds rather than linking to other sites.
• Include a brief description of the video’s content.

Collapsible Panels

Collapsible panels dynamically show or hide sections of content. Use them sparingly.

• Use the Insert/edit collapsible panel button to add panels.
• Do not nest these panels inside one another.
• When using more than one panel, keep one expanded by default and collapse the others. There is a checkbox to control this feature.
• Consider breaking up articles that have many sections into separate documents. 

Purpose

Each article should serve a clear and specific purpose, either describing the solution to a specific issue or explaining how Illinois users interact with a specific service offering. Articles must reflect the current state of a service and be updated as it changes. 

Before creating a new article, check if the information already exists elsewhere and could be added to an existing document instead. 

Navigation

Consider how readers will navigate your documentation.

• For complex subjects, create multiple interlinked articles using the See Also, Up, Next, and Previous document linking feature.
• For topics that need large amounts of information in a single article (such as this one), use collapsible panels and headings to organize content. 

Accuracy

Ensure articles are accurate and up to date by testing the steps and verifying information.

• Follow the instructions as written to confirm they work.
• Regularly update content as interfaces and processes change.

Ownership

Each article must have a designated owner, which can be an individual email address or a shared team resource account. Contact the KnowledgeBase team to establish a resource account. 

Responsibilities associated with article ownership are described in  Answers KnowledgeBase, Policies and Lifecycles.

Some articles contain both public information and internal information which should only be seen by Technology Services staff. Use internal block divs (via the padlock icon in the editor) to restrict internal content.

• Do not include any information protected by HIPAA, FERPA, or similar regulations in any document content.
• Edit screenshots to hide individual account information.
• Use team resource accounts rather than listing individual contact information. 

Access Controls

Several access control options are included under the “Show additional fields” dropdown in the editor:

• Write access: Controls which KB users or user groups can edit the document's content. Set to "Owner group + owner" unless a specific security concern exists.
• Read access: Restricts article visibility to specific KB users or groups, both externally and internally. Use only if your group is correctly configured, and only if there is a specific security concern.
• Site access:
  • external: open to anyone with the link.
  • internal: only accounts that have been given the Internal Viewer permission can navigate to the article (all Technology Services staff, and some IT Pros elsewhere on campus)
  • unit-specific checkboxes allow you to request activation, internally or externally, on other KnowledgeBase instances across campus
  • External articles can be set to only load when viewed internally using the Apply/edit content restriction (padlock) button in the editor
• Campus access: Controls whether a user must log in with an Illinois account to see the document. Set to "Defer to SiteAccess" unless there is a specific security concern.
• Owner: Consider requesting a resource or shared email address be configured as an owner account (useful for service teams where KB maintenance is a shared responsibility)