Purpose

The purpose of this guide is to guide Knowledge base article contributors as they write content for the Knowledge Base. The Knowledge base is a collaborative effort, with many authors from across the university. The goal is a consistent and unified look and feel for our content, as though they were all written by one person.

This guide compliments the Campus Style Guide, which provides a more thorough list of guidelines for communication at UC Davis.

After writing an article review it with the Knowledge Article Quality Checklist. Articles should be reviewed using the checklist at least once a year.

The following topics are covered:

1. 1. Writing Style
      
      1. Voice
      2. Inclusive Language
      3. User Interface Terms
      4. Acronyms
      5. Hyphenations

1. 1. 2. Formatting
      
      1. Text
      2. Headers
      3. Lists
      4. Tables
      5. Capitalization
      6. Hyperlinks
      7. Date Formatting
      8. Numbers

• 1. 3. Graphic Elements
     
     1. Images
     2. Videos
     3. Visual Indicators
     4. Accordions
• 
  
  1. 4. Accessibility
     1. Alt text
     2. Font

5. AI Friendly Content

6. Security

__________________________________________________________________________________________________

1. Writing Style

a. Voice

The voice of the knowledge base is simple and clear with a helpful tone. Write like you speak.

• Be brief and concise.
• Avoid jargon and uncommon words.
• Put the most important point at the beginning.
• When referencing the customer, use the word "you" to keep the tone personal and direct. Avoid less personal terms like "user".
• Active Voice versus Passive Voice
  • Active voice as it makes sentences easier to read. Active voice sentences are structured like the following: subject, action, object (SAO). Passive voice sentences are structured like the following: object, action, subject.
    • Active voice example: "Alli developed the software."
    • Passive voice example: "The software was developed by Alli."

b. Inclusive Language

• Use racially neutral language
  
  • Rather than terms like "blacklist" and "whitelist", use blocklist or allowlist, or simply block or allow.
• Use gender-neutral language.
  
  • Avoid gendered terms like “salesman” or “mankind” in favor of ungendered alternatives.
  • Avoid gendered pronouns "he", "him", "his", "she", "her, and "hers", as well as phrases like “him or her”, "he/she" and "(s)he".
    
    • Use “they” and "their" as the third person personal pronouns for both groups and individuals. Note: Try to use this convention sparingly as it can be confusing. Rewording to eliminate the need for pronouns is preferred.
    • "The" is often a good substitute for "his" or "her" when conveying possession is not required or can be inferred from context.
• Avoid violent language.

c. User Interface Terms

In order to provide a consistent and clear experience to our readers, please use these user interface terms when documenting process steps in software.

d. Acronyms

• On first use, spell out the acronym meaning parenthetically. Example: "IET (Information and Educational Technology)"
• Do not use periods in acronyms. Example: "NASA" not "N.A.S.A". Exception: Two-letter acronyms such as U.S. or U.N.
  e. Hyphenations
• Make sure to hyphenate a word that comes before a noun and acts as a single idea.
  • Example: "Full-scale review."

2. Formatting

a. Text

Most text in articles should be plain with no formatting. This is the default if you simply start typing in the editor. Do not specify a font size.

Bold

• • • Use bold to strongly emphasize critical text, but do so sparingly. Avoid bolding large amounts of text or entire paragraphs; instead, only bold key words and phrases.
      • For gentler emphasis, use italics (see below). Do not use bold and italics together.
    • Bold names for buttons, menus, dialogs, windows, list items, or any other feature in the UI that has a visible name. For example, "Select a Model Category".
    • Use bolded regular text for section sub-headers. Format section main headers using the "Heading 3" style.

Italics

• • • Use to gently emphasize key text, but do so sparingly. Avoid italicizing large amounts of text or entire paragraphs; instead, only italicize key words and phrases.
      
      • For stronger emphasis, use bold (see above). Do not use bold and italics together.
    • Use for any information that is entered into a field. Example: “In the Incoming Mail Server field, type mail.ucdavis.edu.”
    • For accessibility reasons, italics should not be overused.

Underline

Do not use underline to highlight important words or phrases. Generally on the internet, underlined words indicates that there is a hyperlink. Use bold or italics instead (see above).

b. Headers

• Use "Heading 3" from the style drop down for section headers.

• Format section sub-headers as bolded regular text.

c. Lists

• • • Use bulleted lists for multiple items which do not have to be in any particular order.
    • Use numbered lists for items that have to be in a certain order (such as an instruction for a task).
    • Use the same parallel construction for each item in a list. Never mix phrases and whole sentences in a list.
    • Use initial capitalization on all list items.
    • Use periods at the end of a bulleted item only if the item forms a complete sentence or completes the stem sentence before it.
    • In a bulleted or numbered list, add a line break (Shift + Enter) at the end of the text to move the cursor to the next line without creating another list entry.
    • Alphabetize bullet points with less than three bunkers.

d. Tables

Draw tables using the built in HTML editor toolbar in ServiceNow, then fill in the data. Copying and pasting tables from other programs, such as Excel or Word, can result in formatting problems and will needlessly bloat the HTML code, slowing loading of the article.

For help formatting tables, see this ServiceNow help document.

e. Capitalization

• • • Use sentence-style capitalization. This means only capitalize the first word of a sentence, heading, title, etc.
    • Capitalize the first letter of the first word in a numbered or bulleted list.
    • Capitalize proper nouns and acronyms.
    • When documenting UI element labels, match the capitalization shown on the screen.
    • Use lowercase for everything else. When in doubt, use lowercase.

f. Hyperlinks

• • • Text displayed for web hyperlinks should be in one of these two formats:
      
      • The exact title of the linked-to page, is capitalized the same way the link target’s title is capitalized. Example: "Go to the Service Hub", not "Go to https://servicehub.ucdavis.edu/servicehub/?id=ucd_index".
      • A short description of the linked-to page, capitalized like ordinary text. Example: "You can also configure eduroam manually".
    • Do not use “click here”, “here”, or similar vague terminology for link display text.
    • For email links (mailto:), set the display text to the person or group’s name. Example: "Send an email to Luke Skywalker"
    • Configure links to open in a new browser tab. To do this, in the Open link in... drop down, select New window.

• • • Hyperlinks URLs need to start with the link protocol, such as "https://" or "mailto:". Omitting this will cause the link to fail because the system interprets links lacking a protocol as internal to ServiceNow. The allowed hyperlink protocols are https://, http://, mailto:, and data:.
      
      • Exception: Hyperlinks to other pages within the Service Hub should use just the last part of the URL (Everything after "/servicehub/"). For example, if you want to link to https://servicehub.ucdavis.edu/servicehub/?id=ucd_kb_article&sysparm_article=KB0000217, the link URL should only be "?id=ucd_kb_article&sysparm_article=KB0000217". This will allow the page to load more quickly for users.

g. Date Formatting

• • • Use month dd, yyyy or month yyyy format. Examples: January 1, 2020 or January 2020
    • Referencing dates in articles:
      
      • Only use when necessary. For example, an article for a new system not yet live, where the article needs to be published in advance for communications or training purposes.
      • Avoid vague or relative time references: Examples: “next semester”, “in the future”. An exception is for recurring events that happen during s specific month or season every year.
      • Be specific and include the year. Example "Starting in February 2020, UCD students can access..."
      • Remove the date when the date reference is no longer relevant. Generally this is a few weeks or, at most, a few months after the referenced date has passed

h. Numbers

• • • Spell out numbers 1-9 expect when referring to purely numerical measures (e.g., "6%," "8%").
    • Use numerals for 10 and above except at the beginning of sentences. Numerals are also used for ages (“8 years old”).

3. Graphic Elements

a. Images

• • • Use images thoughtfully.
      
      • Do not include screenshots for simple, intuitive actions, such as an installation wizard where the user only has to click "Next" or "OK".
      • Do use screenshots for interactions that are complicated, multi-step, or not intuitive, or to give an overview of a screen or website.
      • Insert screenshots immediately below the relevant text.
      • Note: Images must be updated over time as procedures change, new versions of software are released, and sites updated. Keep this in mind when deciding how many and which images are needed.
    • Acceptable file formats:
      
      • Portable Network Graphics (.PNG) images are preferred. JPEG images (.JPG) are also acceptable if the resolution and quality are adequate.
      • Avoid bitmap (.BMP) and Graphics Interchange Format (.GIF) files.
      • Tip - To convert an image to another format, open it in Microsoft Paint, then "Save as" to the preferred file type. On macOS, the Preview program provides similar functionality using the Export command.
    • Sizing
      
      • Edit screenshots down to focus on the parts of the UI relevant to the step you are describing, but also include enough of the surrounding elements so the user can easily orient themselves.
      • When displayed in Service Hub, images will be automatically and dynamically be shrunk down to fit the available horizontal space.
      • View the article in the portal before publishing to ensure that images are appropriately sized.
    • Borders
      
      • If the screenshot has one or more white edge areas, add a one pixel black border to set it apart from the white background. This is done on the Insert/Modify Image screen by typing "1" in the Border Thickness field.
      • Do not use thicker borders or borders in colors other than black.

b. Videos

• • • Videos can be embedded in Knowledge Base articles using the Insert/edit video button
    • Ensure that there are subtitles or closed captions are provided in the videos you use.
    • When linking to an AggieVideo, use the "Watch on AggieVideo" button. This will add a consistent appearance to video links.

c. Visual Indicators

• To visually highlight something, use a red arrow a rectangle or a circle
  • Here are some examples:
    

d. Accordions

You can add an accordion with expandable sections to organize the content of your articles. This is the suggested style for accordions in the KB: 

For more information on configuring articles, refer to: KB0010558.

4. Accessibility

a. Alt Text

• Alt text should be provided for non-decorative images. If the image displays something already described in the text, alt text is not necessary.
  • Some helpful links to get starting writing Alt Text:
    • From Microsoft: https://support.microsoft.com/en-us/office/everything-you-need-to-know-to-write-effective-alt-text-df98f884-ca3d-456c-807b-1a1fa82f5dc2
    • From Harvard University: https://accessibility.huit.harvard.edu/describe-content-images
• Alt Text for decorative images is not necessary; however, an image must be marked as decorative so that screen readers will take it out of the reading flow and skip over the image.
  • To mark a text as decorative, simply provide an Alt Text of “” to indicate an empty ALT attribute.
• To add Alt Text, click the Insert/edit Image icon on the desired image. Write your Alt Text in the Alternative Description field and click Save.

b. Font

• Avoid setting a font size and instead, change the font style.
  • To change the font style, click on the drop down arrow next to 'Paragraph'.

5. AI Friendly Content

There are several best practices that will help make knowledge base content ingestible by AI.

a. Prioritize Quality and Clarity:

• • • Use simple, direct language that avoids jargon.
    • Provide standalone, context-rich answers for better AI interpretation.
    • Reflect customer terminology to improve accessibility and query matching.

b. Organize Content Logically:

• • • Use clear headings, subheadings, and logical categories to enhance navigation.
    • Utilize bullet points and lists for complex topics or multi-step processes.

c. Optimize Formats for AI:

• • • Prefer plain text over visuals; convert charts and tables into descriptive text.
    • If tables are necessary, keep them simple with clear headers.

d. Maintain a Single Source of Truth:

• • • Centralize information in one platform to avoid inconsistencies.
    • Regularly audit and update the knowledge base to ensure accuracy and relevance.

e. Stay Customer-Focused:

• • • Structure content around common customer inquiries.
    • Ensure the knowledge base is intuitive and empowers self-service.

6. Security

Content in the public Knowledge base is visible to the public, so there are some types of information must never be included in the public KB.

See KB0010286 for a list of information that does not belong in the KB.