Ask Athena writing guide

This article is the home for our style guidelines and Knowledge Owl how-tos as well as the hub for other documents and tutorials about creating content for the LITS Knowledge Base.

Purpose of this guide

This writing and style guide exists for the following purposes:

  • To inform authors about how Ask Athena is styled and what tools and features of Knowledge Owl we use to write in it
  • To provide resources for authors about the accessibility and inclusivity standards to which articles should adhere
  • To provide a reference for any amendments or additions we make to the GSG's guidelines as well as other important internal resources
  • To collect how-to information and tips about using the Knowledge Owl platform
  • To share best practices for writing informational content on the web, especially as pertains to our knowledge base, and to share resources for further learning

This guide is lengthy; to reduce the number of tabs an author might need to reference, our guidelines are all contained on one page. Consider navigating primarily with the table of contents or the find on page tool (Control+F, or Command+F on macOS).

Resources

Our style

As with many online knowledge bases, Ask Athena's styling is built to help readers scan content effectively and to help authors deliver information clearly and consistently. The following sections outline how best to use our styling and the tools in Knowledge Owl to write clear and accessible documentation.

Learn more: For more information about how visitors read—or scan—websites and how to structure an article to encourage a certain mode of reading, check out the following articles from the Nielsen Norman Group. These articles analyze eye-tracking research and recommend formatting guidelines.

Having a consistent style across Ask Athena helps readers identify our site and transition easily from article to article. Furthermore, it helps authors write without worrying about how to style their article and, most importantly, makes it easy for us to update the look of Ask Athena by changing a variable in only one place and having it apply site wide!

Warning: As an author, you have the tools to manually edit the styling within articles. You could (in theory) color every letter in a word differently or manually set the font size of a heading. However, please do not do so. Adjusting the style manually means any site-wide style changes we make will not affect the individual element you edited, making manual editing necessary. Instead, please talk to the Council of Owls if you think an additional style could enhance the site. You have great power; please have great responsibility!

And a final note: as the GSG says, "Break the rules!" Just be certain our content remains accessible and inclusive and is improved by doing so.

Accessibility and inclusivity

Per the College's Web Accessibility Policy, College websites must conform to the Web Content Accessibility Guidelines (WCAG) 2.1, Level AA. To better understand the WCAG 2.1, see the Guidelines' own Understanding section.

[WIP paragraph: DEIAR, reference GSG Word list. MDN: https://developer.mozilla.org/en-US/docs/Learn/Accessibility/What_is_accessibility Guidance on which words to use and which words not to use.]

Tools for testing accessibility

[WIP: ANDI, color contrast app, encycolorpedia.com and colororacle.org for colorblindness simulation]

Understand impairment: Funkify browser extension (Google 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.

Angle brackets in procedures

An angle bracket (>) can be used in a procedural step to combine multiple small actions or sequential menu selections; see the following examples:

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

If you use angle brackets in a procedure, do the following:

  • To use an angle bracket in a procedural step accessibly, insert the Angle bracket (>) snippet instead of >.

This snippet tells a screen reader to say "and then" at the angle bracket. Otherwise, some screen readers might read > as "greater than," resulting in "Next greater than Finish" or "Select Edit greater than Find on page greater than Find."

For example, the second example step given above should have the following input and outputs:

Written in editor
Select Edit{{snippet.angleBracket}}Find on page{{snippet.angleBracket}}Find.
Code view
Select <strong>Edit{{snippet.angleBracket}}Find on page{{snippet.angleBracket}}Find</strong>.
Visual render
Select Edit > Find on page > Find.
Interpreted by a screen reader
Select Edit and then Find on page and then Find.

Note the lack of spaces around the snippet—the snippet includes a nonbreaking space (&nbsp;) on either side of the bracket. The following Read more section provides a full explanation for the HTML-curious:

Style guide: For complete guidelines about using angle brackets in procedures, see Multi-action procedures and Use angle brackets in the GSG.

Color

There are two main things to keep in mind when it comes to colors and accessibility: color contrast ratios and keeping information color agnostic, or not relying solely on color to convey information.

Color contrast

[WIP: note about new standard beyond WCAG 2.1, tools to check]

Color agnosticism

[WIP: 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]

Write accessibly

[WIP: 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.

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 entry exists that could fulfill the same purpose. If there isn't a glossary entry, consider if the term would be a good addition to the glossary, and if it would, give the Council of Owls a hoot!

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

AbbrevLatinEnglish
e.g.exempli gratiafor example
etc.et ceteraand so forth, and so on
i.e.id estthat 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.

Alerts

Alerts, or notices (sometimes notes) as the GSG calls them, are the colored block styles (technically, styled <div> elements) we use to highlight information of special importance to the reader's progress or understanding. Alerts built into Knowledge Owl come in four styles, listed here as they are named in the article editor:

"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

  • Use alerts sparingly. Readers are prone to ignoring banners; as the GSG says in Notes, cautions, warnings, and other notices, "there's evidence that readers skip elements on the page, including notices, that are outside their focus of interest." In other words, visitors to a website—especially to a self-help knowledge base—are typically on the hunt for specific information; therefore, any information that looks like it might be outside the main content of a page is more likely to be ignored.

    To witness this behavior in action with eye-tracking, see Banner blindness revisited: users dodge ads on mobile and desktop from the Nielsen Norman Group.

  • Avoid grouping two or more alerts together, where possible; grouping block stylings reduces the likelihood that readers look at them. If you find yourself needing to do use two back to back, consider an alternative section layout.

  • Preface alert content with a bold term, such as Note or Attention. See the alerts above for the options available for each style. Choose whichever feels most appropriate for the context!

    Warning: Because all information must be color agnostic, or accessible regardless of its color, there must be an indication of an alert's priority level other than its background color. As such, it is important to maintain a consistent relationship between each alert style and the terms that preface its content. Hoot at the Council of Owls if you find a circumstance the provided prefaces don't cover!

  • Indicate a narrow audience in the preface. Mentioning when an alert is only relevant to a subset of readers in the preface is the clearest way to maintain accessibility and catch scanning eyes.
    • Recommended: Attention faculty and staff:
    • Recommended: Warning to students:

Alerts in Knowledge Owl

To add an alert, use the Div Style (magic wand icon) menu in the article editor, as seen in the following image.

Note that we do not have a use case for the Well, Lead, and Reverse Blockquote div styles. As such, please refrain from using them without first consulting the Council of Owls.

Style guide: For the complete guidelines about using alerts, see Notes, cautions, warnings, and other notices in the GSG.

Using alerts in lists is possible and easy to do, but it can be frustrating if done incorrectly and requires a brief excursion into the article editor's Code View (</>). Use the following steps to add an alert in a list:

  1. Insert a paragraph inside the list item around the item's content and another paragraph around the intended alert content.
  2. Apply the alert style to the content in the second paragraph.

For example, in Print from a public printer, we write the following list:

  1. Select Find a printer in the directory, then click Next.

  2. Enter labprint or labprintcolor, then click Find Now.

    Tip: Printer names begin with a building code; look for your printer under the first letter of the building's name. You can also narrow the search results by entering only this letter in the Name field.

  3. Select the printer's name, [...]

As shown in the HTML below, in this example, both step 6 and the tip are within the same <li> element. A <p> element is inserted before "Enter" and closed after "Find Now." (punctuation included). A second <p> is wrapped around the content in the alert, and the Alert Info style is applied.

<ol start="5">
  <li>Select <strong>Find a printer in the directory</strong>, then click <strong>Next</strong>.</li>
  <li>
    <p>Enter labprint or labprintcolor, then click <strong>Find Now</strong>.</p>
    <div class="alert alert-info">
      <p><strong>Tip:</strong> Printer names begin with a building code; look for your printer under the first letter of the building&#39;s name. You can also narrow the search results by entering only this letter in the <strong>Name</strong> field.</p>
    </div>
  </li>
  <li>Select the <strong>printer&#39;s name</strong>, [...]</li>
</ol>

Glossary terms

Any term in Ask Athena's glossary can be inserted into the text of an article, where it will appear with a specially styled underline. When the reader moves the cursor over the term, taps the term on a touch screen, or navigates to the term with the keyboard, a popover appears with the term's definition.

This enables article authors to concisely address the subject of an article without leaving behind readers who aren't familiar with technical terms. The following example demonstrates this:

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

  1. Open Software Center.

  2. In the menu, go to Printers.

  3. And so on...

To insert a glossary term, select the Add Glossary Term button in the article editor. With this interface, you can adjust the term's capitalization, conjugation, and so on to make the term fit naturally into the article. You can see this in the following example, which is keyed to the term printer group:

The following table lists the four printer groups available on campus:

Note: Glossary terms at the end of a line can be tricky to work with in the editor, as typing from the end of a term will cause the "term" to expand with the characters you're typing. One workaround is to start a new paragraph (the term can't carry across paragraphs), type some content, and then delete the paragraph break. This moves the content you added up to continue the paragraph the term was ending.

Feel free to insert glossary terms wherever seems appropriate. Keep in mind visitors are likely to skip around a document and may not have seen a previously inserted copy of the same term. 

Note: Think Ask Athena is missing a glossary term, or think an existing term should be edited? Instead of adding/editing it yourself, let the Council of Owls know so we can make sure the definition covers all the bases!

Headings

Headings define the structure of an article and are a key navigation element for site visitors, whether they are scanning visually or using a screen reader. Headings range in level from Heading 1 (H1) to Heading 6 (H6), but there is rarely cause to use levels below Heading 4.

Heading 2 and Heading 3 are the primary heading levels used in Ask Athena. These heading levels break our articles into sections and subsections and auto-populate the table of contents. 

Style guide: For questions about heading style and usage not addressed below, see Headings and titles in the GSG.

Headings key points

  • Use Headings 2, 3, and 4 for article sections. These are the only heading levels that will appear in the table of contents.
  • Use heading levels in descending order: <h2> then <h3> then <h4>, without skipping levels. H2 is the highest heading level you should use because H1 is reserved for the page title.
  • Keep headings as short as possible, and put the most important idea at the beginning.
  • Avoid "bumping heads," or having two headings without text in between. This leaves readers without any explanatory text at the beginning of the outer section and implies the number of heading levels could be reduced.
  • Only use subheadings when writing more than one subtopic. If there's only one subtopic, keep the information all under the same section instead. You may want to consider a change of format, such as a list, to distinguish information you'd otherwise put into a subsection.
  • Avoid using icons and images within headings. These will not render in the table of contents and may leave extraneous spaces or punctuation.

Additionally, to keep headings consistent across Ask Athena, please note the following points. The reasoning behind this is outlined in Our style, above.

  • Do not put empty paragraphs or line breaks before headings. Similar to the principle of not adding custom styling to text; manual spacing requires manual editing if we ever want to change the styling. If you find a combination of elements where heading spacing styles do not render well, or if you think we should adjust our heading spacing styles, please inform the Council of Owls.
  • Do not manually bold or italicize headings. Similar to the principle of not adding custom styling to text; manual formatting requires manual editing if we ever want to change the styling, and creates inconsistency across our site. Please propose style changes to the Council of Owls.
  • 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.

Headings in Knowledge Owl

To add a heading in the article editor, click the Paragraph Format menu on the left end of the editor toolbar and choose a heading level from the list. Heading levels are applied per-paragraph; you can't (and shouldn't) apply them to individual words.

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 to not use bumping heads.

Images, icons, and videos

[mostly WIP to follow]:

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 Ask Athena 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

Effective links improve an article's accessibility and scannability and improve the navigability of our knowledge base. Different readers experience links differently. For example, 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)

Internal links are links to other pages within our knowledge base, for example, Create a new article and Eduroam: connecting to College wifi. External links take the reader to a different website. For example, the College's Web Accessibility Policy. External links are followed by an external link icon     in the published site to inform readers they will be leaving the knowledge base.

Style guide: For questions about style and usage of links not addressed below, see the following pages in the GSG:

Links key points

  • Contrary to the GSG, off-page links should open in a new tab. In other words, all links in our knowledge base that direct away from the current page should open in a new tab. Check Open in new browser tab when creating a link—internal or external—that isn't linking to a different section in the same article.
  • Links should be plainly styled. Where possible, avoid italicizing link text, and do not add links to headings. Doing so can confuse readers and make them think the link is in some way different from other links or that it is plain text colored differently for emphasis. Bold (<strong>) can be used where appropriate; see Bold in the GSG's Text-formatting summary.

    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 external links. When linking to a page other than the home page on an external site, it is usually best to indicate what the website is in addition to the page name. As an example, in Links in Knowledge Owl below, we write "see Working with anchors on the Knowledge Owl support site."

    As an author, it is up to you how much context is necessary for each link. Another example in Links, "the College's Web Accessibility Policy," gives less context because College policies can be expected to be found on the College's website. Further, in Angle brackets in procedures, the text "a <span> element with an aria-label attribute" gives only implicit context because the result of clicking on the links—learning more about the <span> element and the aria-label attribute—is intuitive.

Links in Knowledge Owl

In the article editor, to link internally to other articles and categories in our knowledge base, use the Insert link to article tool. This ensures the link will remain active even if the linked article's URL changes.

To link externally to another website, use the Insert link tool.

Tip: Add a hyperlink to text you've already written:

  1. Highlight the text.
  2. Click Insert link or Insert link to article. The dialog opens with the highlighted text already filled in.

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

You can also link to sections within articles, such as the section you're reading right now: Links to sections. This is done by appending a fragment to the page's URL, which tells the browser where to scroll to in the page. A fragment identifier consists of a hash # followed by the section's id

—the same method is used in the table of contents

using the id attribute and fragment identifiers, and it is how the links in articles' tables of contents scroll to the specified section. A section's id is appended to the page's URL and referenced with a hash #. (The hash and id together are the fragment identifier.) For example, the URL of this section, Links in Knowledge Owl, is https://lits.knowledgeowl.com/help/writing-guide#links-to-sections, and the id of the section is everything after the hash: links-to-sections.

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

Links can be used in and around style snippets in simple and complex situations. In general, try to 

 For example, in paragraphs in lists below, we instruct the reader to see the <br> HTML specification. If you wish to 

If you wish to insert a link with text both inside and outside a style snippet 

Punctuation

Colon. In addition to Colons, see also Capitalization and colons in the GSG.

Em-dash. Dashes in the GSG directs writers to only use an em-dash glyph (—) instead of two hyphens (--). One way to insert an em-dash is with the Special Characters tool (Ω button) in the article editor; the em-dash can be found under Punctuation, halfway down the  interface. There are also keyboard shortcuts: —

  • Windows "shortcut" 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. (This is called an Alt code.)
  • Windows "shortcut" without numpad: Press Windows+period to pull up the emoji panel, then click Ω for symbols, and then select the .
  • macOS: Press Option+Shift+hyphen.

Snippets

Snippets are blocks of code with functional purposes, such as to create an expandable section. Snippets can be inserted into an article using the Insert Snippet tool in the article editor.

Some snippets come in two parts: the snippet itself and a closing snippet. Be careful when editing an article that you remember to insert a closing snippet!

Our knowledge base uses the following snippets:

Function snippets

  • Angle bracket (>). This snippet enhances accessibility for anyone using a screen reader. You should insert it in place of an angle bracket (>) any time you use one in a procedure.
  • Begin show/hide section (and End show/hide section). Use this pair of snippets to create a "collapsed" section of hidden text underneath a Show more button. (Demo below) The button will be inserted where the first snippet is placed, so make sure to leave a space! Sometimes the button placement is a bit buggy (we didn't write this snippet, so there are some kinks to iron out). For now, reach out to Peter if you run into issues with the button not appearing where you think it should.

    Warning: Do not put Heading 2, Heading 3, or Heading 4 elements inside show/hide snippets; the links they generate in the ToC will not work.

    Site visitors can reveal the text by clicking the button; see for yourself: 

  • Side navigation (and End side navigation).

Style snippets

  • Code (and End code).
  • Hyper-emphasis (and End hyper-emphasis). [WIP: 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.]
  • Keyboard (and End keyboard). Insert this snippet pair immediately before and after any text that indicates keyboard keys, such as Control+V. See Keyboard keys under Text and paragraph formatting below for specific usage instructions.
  • No image style (and End no image style). This snippet pair can be inserted immediately before and after an image to remove the default drop shadow that otherwise applies to images sitewide. This is not necessary for images within tables; they are already exempted from the shadow style.
  • Small (and End small). 

Text and paragraph formatting

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

Bold text. For the most part, refer to the GSG's Text-formatting summary for how to use bold font, but do not worry about its stipulation about using <b> instead of <strong> to render general bold text. While semantic accuracy is important, Knowledge Owl's rich text editor inserts <strong>, and it would be foolish to manually edit the HTML of every article to catch the cases where text should be bold without indicating strong importance. Just keep in mind a browser might not render <strong> text as bold. See also italic text.

Code text. [WIP; note about use for file paths] {{-snippet.relatedArticle}}Test content test test.{{-snippet.endRelatedArticle}}

Style guide: Code in text [WIP context]

Hyper-emphasis. [WIP; 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 text. For the most part, refer to the GSG's Text-formatting summary for how to use italic font, but do not worry about its stipulation about using <i> instead of <em> to render general italics. While semantic accuracy is important, Knowledge Owl's rich text editor inserts <em>, and it would be foolish to manually edit the HTML of every article to catch the cases where text should be italicized without emphasis. Just keep in mind a browser might not render <em> text as italic. See also bold text.

Keyboard keys. To indicate that the user should press a given keyboard key or combination, such as Control+V, use the Keyboard and End Keyboard snippets immediately before and after the key names. For example, Control+V is written as {{snippet.keyboard}}Control+V{{snippet.endKeyboard}}. You can also follow the directions in the GSG, quoted and linked below. Use this style only for keyboard and mouse buttons.

Style guide: Press and type keyboard keys in the GSG states, "To indicate that the user should press a given keyboard key or combination, use the <kbd> element." See this page for guidelines about when and how to use this styling.

Paragraphs in lists. Any list item can contain more than one paragraph. While Shift+Enter (Shift+Return in macOS) is a common means of inserting a <br> line break in text editors, when writing for the web introduce <p> elements within the list item, which can be done in Code View (</> button). Learn more at Multiple paragraph list items in the GSG, and see the <br> HTML specification for which uses are legitimate and which aren't.

Tip: When you add paragraphs within a list item, the line spacing may look a bit funny in the editor, but load a preview and you should see each line has uniform spacing.

Small text. [WIP]

Topic articles

[WIP]

Word list

Alumnae/i
Use instead of alumni. In most cases, alums is also suitable.
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 name/last name
Keep in mind 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
Use with caution. An abbreviation for personal computer. Generally, use a term with greater specificity, as PC is likely to cause confusion due to multiple potential meanings, such as a computer owned personally (as opposed to a public computer), a computer owned personally (as opposed to a College-provided computer), a computer for personal use (as opposed to a server), or a Windows computer (do not use to mean this).

(legacy) Migration instructions

Content migration will occur from June 1, 2022 - July 29, 2022. This section will be deleted after our August 15, 2022 launch.

  • Consult the Tech doc migration tracking spreadsheet and how-to instructions to Create a new article.
  • Choose an article to migrate. Only migrate articles owned by your own group (CEP, EAST, or Web) unless otherwise discussed. 
  • Choose the top-level category or categories and template type and enter them on the Migration Tracking spreadsheet.
  • Copy article content from the Tech Doc and paste it into a Knowledge Owl article template.
    • Date and initial the Transition columns in the Migration Tracking spreadsheet
    • Publishing Status = Draft
  • Format article content in Knowledge Owl.
    • Date and initial the Templating columns in the Migration Tracking spreadsheet
    • Publishing Status = Needs Review
  • Review article content and formatting, check links and tags. This step must be completed by someone other than the person who formatted the article.
    • Date and initial the Clean-up columns in the Migration Tracking spreadsheet
    • Publishing Status = Published

Questions about content migration? Reach out to a project team member or review the 5/24/22 LITS knowledge base training session recording.