Knowledge Management Style Guide

The purpose of this guide is to support Knowledge Base contributors in creating clear, effective content. Because the Knowledge Base is a collaborative effort involving many authors across the university, the goal is to maintain a consistent, unified style so all articles read as though they were written by a single voice.

The following topics are included:

1. 1. Writing Style
      
      1. Article Titles
      2. Voice
      3. Inclusive Language
      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. 1. 3. Graphic Elements
      
      1. Images
   2. 4. Accessibility
      1. Alt text
      2. Font
      3. Accessibility Checker

5. AI Friendly Content

6. Security

__________________________________________________________________________________________________

1. Writing Style

a. Article Titles

• Article titles should be written from the user's perspective. Focus on the problem the user is trying to solve.
• Focus on symptoms, not solutions.
• Use language users would understand. Avoid technical jargon.
• Be specific.

Writing Good Article Titles

Poor	Better
SEO Best Practices	How can I improve my website's search ranking?
Network Latency Optimization Strategies	Why is my internet so slow? Troubleshooting Tips
Duo Exception Request	Can I opt out of Duo?

b. 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."

c. Inclusive Language

• 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.
• Use racially neutral language.
• Avoid violent language.

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 IT Service Hub", not "Go to https://berkeley.service-now.com/itservicehub
  • A short description of the linked-to page, capitalized like ordinary text. Example: "How to Toggle Windows Laptop Projection"
• 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"
• 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:.

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.

4. Accessibility

a. Alt Text

• Alt text should be provided for non-decorative images. To add Alt text, select the image, then click the Insert/Edit image button on the toolbar. Alt text is entered into the Alternative description field.

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

c. Accessibility Checker

ServiceNow has a built in Accessibility Checker on the toolbar. Use this feature before publishing any article to help you review for accessibility issues.

 

5. AI Friendly Content

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

a. Use clear language

• • 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. Use descriptive text

• • Plain text is better than images.
  • Convert charts and tables into descriptive text.
  • If tables are necessary, keep them simple with clear headers.

d. Stay customer-focused

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

6. Security

Content in the IT Public Knowledge Base is accessible to anyone, so certain types of information must never be included. This includes:

• Credentials or authentication data (passwords, API keys, tokens)
• Personally identifiable information (PII) or any sensitive/regulated data
• Confidential business information (financials, strategy, trade secrets)
• Legal or compliance-sensitive content (contracts, investigations, audit details)
• Detailed system architecture or internal infrastructure information
• Security procedures, incident response details, or monitoring thresholds
• Source code or technical implementations that expose internal logic or secrets
• Internal URLs, admin endpoints, or non-public system access paths
• Third-party or vendor confidential information
• Known vulnerabilities, weaknesses, or insecure workarounds