KnowledgeOwl writing guide

Last Modified on 07/23/2024 8:55 am EDT

This article is home to our style guidelines and how-to's for KnowledgeOwl, as well other authorships tutorials.

Preamble

Purpose of this guide

Attention: This guide is lengthy! Consider navigating using Ctrl+F on Windows or Command+F on macOS.

  • Inform authors of current knowledge base styling and features
  • Provide accessibility and inclusivity guidelines for all KnowledgeOwl content to adhere to
  • Provide a reference for amendments or additions we make to the GSG's guidelines
  • Collect how-to information and tips
  • Share best practices for writing informally on the web


Resources

Google Developer Documentation Style Guide (GSG)

https://developers.google.com/style

For most authorship guidelines, our knowledge bases default to the GSG. Be sure to review it before you begin writing!

Note: Why the GSG? 


Our style

Our styling is built to help readers scan content effectively and assist authors in delivering information clearly and concisely. This also allows readers to identify our site and easily transition from article-to-article.

Learn more: Interested in how readers scan websites? 

Warning: Never manually adjust styling! Why not? 

Per the GSG, "Break the rules!" -- but be certain content remains accessible, inclusive, and is improved by doing so.

Abbreviations

Contrary to the GSG, use of the Latin abbreviations e.g., i.e., and etc. is acceptable, but only in parenthetical expressions and alerts. Use periods in these abbreviations, followed by a comma or other appropriate punctuation. In regular text (i.e., text outside of alerts or parentheses), use the English equivalent of the abbreviation. We recommend you use these abbreviations sparingly; as with parenthetical expressions, consider whether an abbreviation is necessary or if the information is important enough to write outside of parentheses.

Tip: When using i.e., check if a glossary term already exists that could fulfill the same purpose. If there isn't one, and it would make a good addition, submit a Change Request!

  • Correct: Web browsers (e.g., Firefox) can be used…
  • Correct: Web browsers such as Firefox can be used…
  • Incorrect: Web browsers, e.g., Firefox, can be used…

Consult the following table for meanings and English equivalents of Latin abbreviations:

Abbrev Latin English
e.g. exempli gratia for example
etc. et cetera and so forth, and so on
i.e. id est that is, in other words

Style guide: These guidelines are adapted from the MDN Web Docs Writing style guide. For information on all other abbreviations, refer to Abbreviations in the GSG. Additionally, see etc. in the GSG Word list and Parentheses in the GSG for guidance about their respective usage.

Accessibility and inclusivity

Attention: Per the College's Web Accessibility Policy, our knowledge bases must conform to WCAG 2.1 level AA.

Work-in-progress

DEIAR, referencing GSG Word list


Angle brackets

An angle bracket (>) can be used in step-by-step instructions to combine multiple short actions or sequential menu selections, such as the following.

  1. Click Next > Finish.
  2. Select Edit > Find on page > Find.

Warning: When using an angle bracket to combine steps, always use the "Accessible angle bracket" snippet. Why? 

Note: How the Accessible Angle Bracket snippet works 

Learn more: For additional guidance, see Multi-action procedures and Use angle brackets in the GSG.


Color

There are two main aspects to color and accessibility: color contrast ratios and maintaining color agnostic content.

Work-in-progress

Color contrast

New standards beyond WCAG 2.1, available tools

Color agnosticism

Information must be accessible without color. For example, a "warning" alert section's level of urgency must be indicated in some mode beyond its red color.

  • Tool: encycolorpedia.com; a color palette tool. At the bottom of each color page are simulations of multiple types of colorblindness
  • Tool: colororacle.org; free app for simulating types colorblindness


Testing accessibility

Work-in-progress

ANDI, color contrast app, encycolorpedia.com and colororacle.org for colorblindness simulation

Understand impairment: Funkify browser extension (Chrome only)

Tool for simulating a variety of impairments of cognition, reading, motor function, and vision. Effects include dyslexia, ADHD—editor's note: surprisingly accurate—Parkinson's, partial vision loss.


Writing accessibly

Work-in-progress

Callout from GSG: Don't use color, size, location, or other visual cues as the primary way of communicating information. Don't assume the reader knows the physical layout of the page, both for accessibility and desktop/mobile agnosticism.

"Don't use directional language to orient the reader, such as above, below, or right-hand side. This type of language doesn't work well for accessibility or for localization. If a UI element is hard to find, provide a screenshot."—GSG: Procedures (unfinished link)

Examples in practice:

  • Recommended: Click the Start button in the taskbar.
  • Not recommended: Click the Start button in the bottom-left corner of your screen.

Alerts

Alerts are used to highlight information of different types. KnowledgeOwl has four main styles.

"Alert info." This information is relevant, but not necessary. Used for notes and tips.

Preface terms:

  • Note:
  • Tip:
  • More information:

"Alert warning." The reader should consider this information as they continue.

Preface terms:

  • Caution:
  • Attention:
  • Before you start,

"Alert danger." The reader should stop what they are doing until they have considered this information. 

Preface terms:

  • Warning:

"Alert success." This information will provide the reader with a deeper understanding of the topic.

Preface terms:

  • Learn more:
  • Style guide: (in internal documents only)


Alerts key points

  • Preface alerts with a bold term, such as Note or Attention

    Warning: To ensure information is color agnostic, there must be an indication of an alert's priority level other than its background color. As such, maintaining a consistency between alert style and terminology is key!

  • Avoid grouping more than 2 alerts together
  • Indicate the intended audience in the preface
    • Attention faculty and staff:
    • Warning to students:
  • Ensure an alert is a good fit
    • Some readers may skip banners, so it is important to consider what information is housed within them and its context with the remainder of the article.


Using alerts

To add an alert, use the Div Style () button in the article editor.

Attention: Please refrain from using the Well, Lead, and Reverse Blockquote div styles.

Learn more: For the additional guidance when using alerts, see Notes, cautions, warnings, and other notices in the GSG.

Note: Using alerts in numbered or bulleted lists. 

Glossary terms

Note: Knowledge Base missing a Glossary Term? Submit a Change Request!

Terms in a knowledge base's glossary can be inserted as stylized text that presents the term's definition. This allows authors to concisely address the subject of an article without re-defining a term in multiple places.

To add a campus printer on a College-provided Mac:

  1. Open Software Center.

  2. In the menu, go to Printers.

To insert a glossary term, use the Add Glossary Term () button in the article editor.

Attention: Glossary terms at the end of a line 

Headings

Headings define the structure of an article and are a key navigation element, ranging from levels H1 to H6. Heading 2 and Heading 3 are the primary levels used in KnowledgeOwl.

Heading key points

  • H1 is reserved for the article title
  • H2, H3, and H4 auto-populate in the Table of Contents
  • Always use heading levels in descending order...NEVER skip a heading level
  • Keep heading as short as possible
  • Avoid using icons or images -- these will not render in the Table of Contents
  • Avoid two headings without text in-between
  • Avoid sub-headings when there's only on sub-topic

Warning: To ensure consistency across knowledge bases, never do the following.

  • Do not put empty paragraphs or line breaks before headings. Similar to custom styling for text, manual spacing requires manual editing should we ever need to make a change. For site-wide changes, submit a Change Request.
  • Do not manually bold or italicize headings.
  • Do not put links in headings. Link styling can be confused to be a differently styled heading, obscuring the nature of the link. Additionally, links are best introduced with context, which a heading cannot sufficiently provide.


Using headings

To add a heading, click the Paragraph Format button in the article editor, and select an appropriate heading level.

Learn more: For additional guidance about heading style and usage, see Headings and titles in the GSG.

Tip: Pressing Enter (or Return in macOS) at the end of a heading will set the style on the new line back to normal paragraph styling—a helpful reminder not put two headings back-to-back.

Images, icons, and videos

Work-in-progress

Default style

Images by default have a light drop shadow applied to them to make it easier for readers to percieve the difference between images and other content. However, this may not always be desirable. Use the No image style snippet to disable this styling.

Alternative text

Always add [alt] text to images and icons unless they are purely decorative; [alt] is a mandatory attribute of the [<img>] element. If an image or icon is purely decorative, leave the [alt] text blank; a [WIP script] will add an empty [alt] attribute to the image to maximize compatibility and accessibility.

For images, [alt] text can be added with the i button in the editor image interface.

Icons that are purely decorative should have the following attribute in their HTML: [aria-hidden="true"]. This hides the icon from screen readers so it doesn't hamper the visitor experience. Most icons on KnowledgeOwl are decorative, but if an icon is not purely decorative and adds information to the page, make sure it has [alt] text and does not have the [aria-hidden="true"] attribute. (Operating system icons such as and are decorative; they do not need [alt] text but should not be used on their own.) An icon added with the [<i class="fa/bi-[...]"></i>] font method does not support the [alt] attribute. Only use this method for decorative purposes. Insert an [<svg>] to add a functional or informational icon.

Figure captions

Don't use the Image Caption tool in the Knowledge Owl image widget; the captions it makes are not associated with the image in a way that is universally comprehensible to screen readers. Follow the GSG's guidelines for Text associated with images instead.

This is a work in progress, and tools to make adding accessible captions easier may still be added!

Links

Links can improve an article's accessibility and readability as well as the navigability of a knowledge base.

  • Internal links: from page within a knowledge base to another
    • This ensures a link isn't broken, even when a URL changes!
  • External links: from a page within a knowledge base to a different website
    • These are followed by an icon     to inform readers they will be leaving the knowledge base.

Note: Different readers experience links differently! Users of screen reader software often jump from one link to the next without reading the words in between. Other readers visually scan a document to find relevant links. (Source: GSG)


Links key points

  • Contrary to the GSG, external links should always open in a new tab
  • Links should not have additional styling, such as italicizing or bolding

    Attention: An exception is when you add a link within <code> text, such as if you reference and link to a page about the HTML aria-hidden attribute. See Code text in Text and paragraph formatting below for more.

  • Give context to the link's destination


Using links

To add an internal link, click the Insert Link to Article () button and select the article you'd like to link to.

To add an external link, highlight the text you'd like to link and click the Insert Link () button.

Learn more: For additional guidance on the usage of links, see the following pages in the GSG.

Work-in-progress

Link to sections

You can also link to sections within articles, such as the section you're reading right now: Links to sections. The URL for this section is https://lits.knowledgeowl.com/help/writing-guide#links-to-sections. You can see the "hyperized" fragment at the end; this is what tells the browser where in the page to scroll to.

More information: A fragment identifier in a URL consists of a hash # followed by the id of an HTML element. Any element can have an id attribute, but most don't. The id attributes of the headers in our articles, used whenever a link in the table of contents is clicked, are created automatically. It's recommended you stick to using these, as an id added manually is easy to accidentally delete in the rich text editor.

This is explained well in an alternative way in A quick primer on URLs and paths on MDN Web Docs.

Page sections on external sites

To link to a section on an external site, such as Steps with goals in the GSG or Accessibility guidelines and the law on MDN Web Docs, you don't need to take any special steps in Knowledge Owl; simply paste the section's URL in the Insert link tool like any other link. To find the link, many sites—especially modern knowledge bases you may be linking to—provide a way to copy or display the URL of a section. You can also find the URL of a section by clicking in the page's table of contents, if there is one. See Link to other sites in the GSG for additional details.

Sections within the same Ask Athena article

Sections in another Ask Athena article

Find the URL of a section with any of the following methods:

Method 1

  1. Click the Copy link to clipboard button at the end of the section heading.
  2. Paste the URL where desired to use it or read it.

Method 2

  1. Click the link to the section in the table of contents.
  2. Read the URL in your browser's address bar.

Method 3

You can also link to sections within articles, such as the section you're reading right now: Links in Knowledge Owl. This is done using anchors, and it is how the table of contents in articles can scroll to a specific article section. A section's anchor is appended to the article's URL and referenced with a hash #. For example, the URL of this section, Links in Knowledge Owl, is https://lits.knowledgeowl.com/help/writing-guide#links-in-knowledge-owl, and the anchor of the section is everything after the hash: links-in-knowledge-owl. You can find the link to a section by clicking the Copy link to clipboard button next to the heading or by clicking the link in the table of contents.

To link to a section using anchors, see Working with anchors on the Knowledge Owl support site, specifically the subsections "Insert a link to an anchor within the same article" and method two of "Insert a link to an anchor in another article."

Links with snippets

Punctuation

Colon

See Capitalization and colons in the GSG.


Em-dash

In general, an em-dash (—) should be used instead of two hyphens (--). This can be done by clicking the Special Characters tool (Ω button) in the article editor; the em-dash is listed under "Punctuation".

Note: The following shortcuts can be used for adding an em-dash.

  • macOS: Press Option+Shift+hyphen.
  • Windows (without numpad): Press Windows+period to pull up the emoji panel, then click Ω for symbols, and then select the —
  • Windows (with numpad): Turn num lock on, then hold down the left Alt key and type 0151 on the numeric keypad (numpad), and then release Alt.

Snippets

Snippets are blocks of code that can be easily inserted using the article editor. 


Using snippets

Warning: Snippets frequently come in two parts: a BEGIN and END. Both are required.

To insert a snippet, click the Insert Snippet () button and search for the snippet you'd like to add.


Functional snippets

Angle bracket (>)

Enhances accessibility for anyone using a screen reader. Insert this in place of an angle bracket anytime it is used in a step-by-step procedure.


Collapsible Section (BEGIN and END)

This pair of snippets creates a collapsible/accordion section that allows for text to be hidden beneath a Show more button.

Warning: Never put a Heading inside a collapsible section, as it will break the Table of Contents.

Attention: Consider whether visitors are likely to navigate the article using the table of contents, which minimizes the need to hide content. Always clearly indicate what they contain, and avoid hiding key content between them. While the section is collapsed, the following complications are present:

  • The content is hidden from navigation tools like find on page (Control+F, or Command+F on macOS) and screen readers.
  • Visitors who can see cannot visually scan for the content.
  • The content cannot be linked to.
  • The content will not appear if a visitor prints the page, even if they use the PDF or Print buttons in the article title.

To improve accessibility, use this pair of snippets adjacent to relevant headers and use introductory sentences, similarly to introductions for lists and tables, as seen in the GSG.


Side Navigation (BEGIN and END)

This pair of snippets must start and end every article, to ensure the Table of Contents is generated properly.


Style snippets

No image style (BEGIN and END)

This pair of snippets can be inserted before and after an image to remove the default drop shadow that otherwise applies to images site-wide. This is not necessary for images within tables; they are already exempt from the shadow style.


Text style: Code (BEGIN and END)

I am an example.


Text style: Hyper-emphasis (BEGIN and END)

Work-in-progress

Note: If you are using this snippet across multiple lines (typically paragraphs) of text, add it and close it on each line. This snippet adds a <span> element which the article editor will not allow to stretch across paragraph breaks. Avoid using a <br> line break; see the <br> HTML specification for which uses are legitimate and which aren't.

I am an example.


Text style: Keyboard (BEGIN and END)

Use this snippets to indicate any text that is a keyboard key (e.g., Ctrl, Space, Command, etc.)

I am an example.


Text style: Small (BEGIN and END)

I am an example.

Text and paragraph formatting

Alignment/justification

Use left alignment unless there is a clear reason to do so otherwise. This aids visitors who can see in finding information quickly by scanning down the left side of the article. You can find links to supporting eye-tracking research in Our style, above.


Bold

Refer to the GSG's Text-formatting summary for how to use bold font.

Attention: Disregard the GSG's concern regarding <b> versus <strong>.


Code

Work-in-progress

Note about use for file paths


Hyper-emphasis

Work-in-progress

When bold is not enough, make it hyper.

Warning: Do not use hyper-emphasis text in alerts. Because this style is a brighter color, it does not have an accessible contrast ratio against the colored backgrounds.


Italic

Refer to the GSG's Text-formatting summary for how to use italic font.

Attention: Disregard the GSG's concern regarding <i> versus <em>.


Keyboard

Use the Text style: Keyboard snippets before and after keyboard keys. Only use this for keyboard and mouse buttons.

Learn more: For additional guidance as to when this snippet should be used, see Press and type keyboard keys in the GSG.


Paragraphs inside of a list

Note: When adding a paragraph within a list, the line spacing may not appear correctly in the article editor. Click Preview to view the actual line spacing.

Any list can contain more than one paragraph using one of the following methods.

  • Enter the Code View (</>) and add a <p> element within the list
  • Press Shift+Enter/Return to insert a <br> line break

Learn more: See the <br> HTML specification for which uses are legitimate and which aren't.

Topic articles

Work-in-progress

Word list

Alumnae/i

Use instead of alumni.

College computer

A computer provided by the College or purchased with College-provided funds. In cases where you need greater specificity, use College-provided computer. College-owned is also acceptable, but is less preferred.

First/last name

Keep in mind that not all cultures say personal names before family names. If it doesn't confuse the meaning of your writing, consider alternatives such as personal name, family name, and surname.

PC

Do not use. While this is an abbreviation for personal computer, it is likely to cause confusion due to its various possible definitions such as:

  • computer owned personally (as opposed to a public computer)
  • computer owned personally (as opposed to a College-provided computer)
  • computer for personal use (as opposed to a server)
  • Windows computer


Related Articles