Library:Circle/Creating and Editing Wiki Pages

Summary

This page is intended as a quick reference guide to assist cIRcle Office members with creating and editing cIRcle Wiki pages. Recommendations for creating accessible pages and content are provided to support accessible content development.

How, when and why cIRcle uses Wiki

cIRcle uses Wiki pages for a variety of purposes, such as documentation about cIRcle’s service offerings and workflows, user guides, and to share procedures and collaborate with staff from the wider UBC Library. Some Wiki pages are used in cIRcle’s WordPress site using the ‘Wiki-Embed’ plugin.

Wiki pages facilitate collaboration by designated editors, allowing for frequent and timely updates to key internal procedures and public-facing information such as user guides.

Namespaces

UBC Wiki pages are grouped into collections called namespaces, which differentiate between the purpose of the pages at a high level. Pages created for cIRcle staff use or as user resources (e.g. user guides) should be published in the Library namespace.

Within a namespace, different types of pages can be created:

• Main: used for cIRcle Wiki pages of any type published within the Library namespace. Pages in the Library namespace can only be edited by authorized Library Wiki users.
  • Title format: Library:Circle/[Page title]
• Documentation: used for cIRcle Wiki pages that involve external project partners, such as workflow documentation and support guides. Pages in the Documentation namespace can be edited by any Wiki user.
  • Title format: Circle/[Page title including project partner name]
• Sandbox: used for drafting or testing Wiki pages and content. When a Sandbox page is ready to be published, the content should be transferred to an existing Wiki page or moved to a new Library or Documentation namespace page.
  • Title format: Circle/[Page title]

Wiki Categories

cIRcle uses Categories to organize Wiki pages into groups:

• Circle: leading category used for pages that provide information on cIRcle workflows and guidelines, and user guides. These pages are referenced throughout internal cIRcle documentation and the cIRcle WordPress site but are not embedded directly into WordPress.
• Circle Archive: sub-category used for inactive pages that are maintained for referential purposes only.
• Circle Projects: sub-category used for Documentation namespace pages that provide information on cIRcle workflows for specific projects involving external project partners.
  • If a project has more than one Wiki page, a second Category tag for the project name can be added to allow all of the project’s pages to be accessed through a single Category link (e.g., From the Ground Up)
• Circle Website: sub-category used for pages that are embedded into cIRcle’s WordPress site using the Wiki Embed plugin.

Accessibility

Web accessibility means that websites and related tools and technologies are designed and developed so people with disabilities can use them. Prioritizing web accessibility in the creation, design and use of cIRcle Wiki pages and content will ultimately benefit everyone and help fulfill cIRcle’s Open Access mandate.

The Web Content Accessibility Guidelines (WCAG) by the W3C Web Accessibility Initiative (WAI) are recognized as an authoritative source to understand and meet web accessibility standards and are built on four core principles, ensuring that web content for all users must be:

1. Perceivable: Users must be able to perceive information and interface components (e.g. images or buttons) using one of their senses;
2. Operable: All users must be able to interact with interface components and navigation
3. Understandable: Users must be able to understand information and how to interact with a website in a logical way
4. Robust: Web content must be stable and able to be interpreted in a reliable way by users and software (including assistive technologies) over time and as technology changes.

For more information about WCAG’s Four Principles, see the Introduction to the Fundamentals of Web Accessibility by WAI.

Version 2.2 of the WCAG has been used to develop the following recommendations.

Creating and Editing Pages

To create or edit a Wiki page, log into UBC Wiki using your CWL. If you are unable to login using your CWL, contact the cIRcle Specialist.

Tip! CWL sessions in Wiki are set to time out after approximately 1 hour. To avoid losing work due to session time out, it is recommended you save your work every 30 minutes.

Creating Pages

To create a new page, follow the instructions provided on Help:Create_New_Page and Library:Home#Wiki_Guidelines.

• To create a new page using the Create a New Main Space Page box, use the following page title format: Library:Circle/[Page title]
  • Including the “Library:Circle/” prefix will ensure that new pages are created within the larger Library namespace.
• If you are creating a draft page to prepare new content for migration to an existing published page, or if you need a page to test formatting or presentation methods, use the Sandbox. Use the following page title format for Sandbox pages: Sandbox:Circle/[Page title].
  • The prefix ‘Sandbox’ will be autopopulated in the 'Create a Sandbox Page' form. Maintain this prefix when inputting your page title.

Tip! Enter your page title in normal sentence case. Any spaces in the page title will be converted to underscores in the page address.

After creating your page, tag your page with “Category: Circle” or the appropriate sub-category (e.g. “Category: Circle Website”). This will ensure that your page can be searched and discovered across the Wiki. Category tags may be updated at any time.

Adjusting the Sort Key

To have your page appear in alphabetical order within "Category: Circle," a sort key must be added to the category tag. This can be done when the cIRcle category tag is applied by editing the text found in Categories > Options. To ensure your page will appear in alphabetical order, remove the namespace prefix from the sort key so only the page title is included.

Editing Pages

The Wiki Visual Editor’s Formatting Toolbar is the recommended tool for editing Wiki pages. Further information about editing using the Visual Editor can be found at Learn how to format in Visual Editor.

For more complex edits, the Wikitext editing option may be used. Further information about editing using Wikitext can be found at Learn how to format in Wikitext.

Important! Consider how your Wiki page will be viewed when formatting your content. If your page will be embedded into cIRcle’s website, the page’s formatting may appear differently in WordPress. To verify edits on Wiki embedded pages, save your changes in Wiki and then go to the associated WordPress page and click “Refresh Wiki content” at the bottom of the page (you must be logged in to the WordPress admin site to see the Wiki content status box at the bottom of the page).

Selecting colour and contrast

All page elements (text and non-text-based) should be designed or chosen thoughtfully, with attention paid to colour choice(s) and ensuring a high contrast ratio. This helps level accessibility barriers for users who are colour-blind or who have other visual disabilities. Colour should not be used as the only visual means of conveying information or indicating a required action.

• For visual examples of effective use of colour and tone, see the OER Toolkit Best Practices 2: Images

It is recommended to test colour choices and contrast ratios for all elements prior to Wiki page publication. Reputable external tools include:

• Basic contrast checker: WebAIM Contrast Checker (use an eyedropper tool in Paint or a similar program to identify colours, then input them)
• For images: Color Checker for ADA image Compliance
• For whole, published web pages: Web Accessibility Evaluation Tool (WAVE)

Writing and Organizing Content

Define your page’s purpose and identify user goals to guide the organization of your content. Clearly organized content benefits everyone and helps reduce accessibility barriers. A plain language page summary should be provided at the start of the page. This is a useful way to orient users to the page’s purpose and will inform your use of headings and subheadings.

Write for the widest possible audience by using plain language and clear instructions. Reduce the use of jargon and provide definitions of technical terms, if needed. Text readability may be tested using tools such as Readability of Wikipedia and/or the Hemingway App.

Your page should be organized using sections and sub-sections. Section headings should be action-oriented and descriptive, so that users will know what will be found within that section. Headings should follow a logical, hierarchical structure and should be formatted using the drop-down headings menu in the Wiki Formatting Toolbar. Only one Page Title heading should appear on your page, with sections and sub-sections using Heading, Sub-headings 1, 2, 3 as appropriate.

Tip! When Wiki pages are embedded in WordPress, headings may display differently in accordance with the embed code (e.g. as tabs or as an accordion).

When creating instructional content, it is important to make sure that the instructions and accompanying content (e.g., screenshots) are presented in chronological order. Information necessary to performing an action or making a decision (e.g. a Tip! box) should be presented before any text describing a final action (e.g., “When finished, select the Submit button”).

When writing and organizing your page's content, consider if your page: Uses logical organization for the content, based on anticipated user needs? Uses headings and subheadings that are descriptive, concise and action-oriented (e.g., “Create an account”)? Are headings ordered logically? Uses plain language and concise sentences, rather than jargon and technical terminology? Uses chronological presentation of instructions and their accompanying content? Uses instructions that describe all steps required to complete an action or task, using device-agnostic terms like “select” and “choose” instead of “click” or “tap”?

Formatting Page Text

Text should be formatted using the Wiki Formatting Toolbar. To make text more accessible to users with dyslexia and those who use screen-readers, avoid the use of italics, underlining, strikethroughs, and colour-coded text; use bold instead. Important information must be captured in the text itself; do not use text styling such as custom colours to convey importance.

Note: Certain formatting elements, such as font style, are not able to be modified as they are determined by the UBC Library style guide. For pages that are embedded in WordPress, formatting elements may display differently than they do in Wiki.

Multi-step processes or dense information should be presented as formatted lists, rather than in paragraph form. Select either ‘Bullet list’ or ‘Numbered list’ from the Formatting Toolbar.

Limit the use of special characters (those not found on a standard computer keyboard) where possible. Special characters may be added using the Special Character tool (represented by an Omega symbol) in the Formatting Toolbar. If the desired special character is not included in Wiki’s list of supported characters, transcribe the characters as best you can using a standard keyboard set.

When formatting your page's text, consider if your page: Uses headers to create whitespace between paragraphs or sections? Uses formatted lists for multi-step processes? Uses italicization, underlining, bolding, or other text styling to convey importance? If so, revise your text to capture the importance and remove the text styling. Uses special characters that are recognized by screen readers?

Formatting Tables and Boxes

cIRcle’s Wiki pages often include tables or boxes, such as ‘Tip!’ boxes in cIRcle User Guides. When creating a table or box, it is important to ensure it is formatted correctly so they will be readable by screen-readers.

Tables are created in the Wikitext Editor. Tables should have a simple layout and logical structure. When creating a table:

• Use Wikitext to markup the table’s row and column headers
• Always include a title and/or caption for the table
• Avoid using merged or split cells; use the simplest possible table layout to maximize readability
• Include adequate cell padding to provide space around the data in each cell
• Alternate background shading of rows to improve readability

Boxes, such as ‘Tip!’ boxes, are created using a styled Table. The easiest way to ensure consistent formatting of boxes within and across Wiki pages is to copy and paste an existing Box:

1. Locate the appropriate box from the same or another Wiki guide; pay attention to the icon used within the box (if applicable)
2. Using the Visual Editor, click one WikiTable column, hold shift, click the second column, and then use the keyboard command CTRL+C to copy the box
3. Use keyboard command CTRL+V to paste the box in the appropriate place on your page and edit the icon and text as necessary

If necessary, styled TablesTables can be created using Wikitext source code. The following source code can be used to recreate cIRcle's standard styled 'Tip!' box: {| class="wikitable" style="width: 100%;" |- | style="border-right: hidden; border-width: 1px; width: 7%;" ||'Insert image link here and set to 100px width'|| Tip! Add your Tip text here. |}

The icon used in a box may change depending on the type of tip or information being provided and are assigned helpful alternative text (alt text). Available icons are:

Icon Image	Name of Icon	Description of Icon & Use
	Box with a checkmark	Represents a completed item on a checklist. Used for: summary checklists provided at the start of a submission guide or review checklists throughout a user guide.
	Exclamation Mark	Represents an important note or warning to review before proceeding. Used for: identifying key steps in a process, or requirements for successful completion of an action.
	Lightbulb	Represents a tip or suggestion for completing a task efficiently. Used for: quick tips or notes providing definitions or additional information about how to complete an action within a process easily.
	Question Mark	Represents an answer to frequently asked questions or issues. Used for: identifying additional resources, training, or other means of assistance for answering questions or resolving issues.
	No symbol	Represents an exception to standard practice. Used for: identifying an exception to the written instructions, including a description of why the exception may be allowable.

Adding or Editing Links

Users should know where a link is, and where it will take them. Two main types of links can be created on the UBC Wiki:

• internal links to sub-sections of the same page Wiki page. These will display as blue linked text.
• external links to other websites or Wiki pages. These will display as blue linked text with a pop-out window icon next to the linked text.

To add a link to text, highlight the appropriate text and click the Chain Link icon in the Visual Editor Formatting Toolbar. In the ‘Add a link’ pop up box, select your type of link (‘UBC Wiki’ or ‘External site’) and paste the URL into the text box, then click ‘Done’.

Creating a section header link

Previously, section headers within Wiki pages were assigned anchor links that could easily be used as a hyperlink elsewhere on the page or in another related Wiki page. As of November 2023, headers are no longer assigned unique anchor links. To use a section header as a hyperlink:

• For internal links: combine the page name including Namespace with a hash character (#) and the section header (case sensitive), with underscores (_) in place of spaces: Sandbox:Circle/Creating and Editing Wiki Pages#Creating_a_screenshot
• For external links: combine the page URL with a hash character (#) and the section header (case sensitive), with underscores (_) in place of spaces: https://wiki.ubc.ca/Library:CIRcle_License_Version_History#Version_2.2_to_3.0

Formatting Contact Links

Users should be offered diverse, accessible options for contacting cIRcle. Two ways to provide contact information on Wiki pages are:

• Direct users to cIRcle’s Contact Us page using an external link
• When linking to the Contact Us page is not appropriate, provide a contact email address in the format example@example.ca and formatted as plain text. If available, include a phone number as an alternate means of contact.

When adding or editing links, consider if your links: Use descriptive link text. Ensure the purpose of the link is clear and avoid general phrases like ‘Click here,’ or ‘More’. Use hyperlinks limited only to the relevant words. If your hyperlinks have been applied to the whole sentence, revise and ensure only the words directly related to the link are included within your link text. Use the correct formatting for contact information. Ensure contact information is set as an external link or offered in the form of an email address formatted as plain text.

Publishing or Moving a Page

Wiki pages may be moved to: publish a completed Sandbox draft or to rename an existing Wiki page. More information about moving pages can be found at Moving a Page.

To publish or rename your page:

1. At the top right toolbar, select 'More' > 'Move' (next to View History)
2. In the 'Move' panel, edit the New Title options as necessary:
   1. Select the appropriate Namespace (Library or Documentation) from the dropdown menu
   2. Maintain or edit your page title as necessary, following the correct format for the chosen Namespace
3. After moving your page, check all internal section header links to ensure they have not broken. If needed, update the internal links with the page's new namespace and/or name.

Moving a page will create a redirect, so moving and renaming a page should not break any existing links.

Creating and Uploading Audio-Visual Content for cIRcle Wiki Pages

As a general rule, only images or multimedia that convey information or meaning should be included in cIRcle Wiki pages. Images or multimedia that are purely decorative or images of text should not be used. All images must include appropriate alternative text (alt text) to convey the image’s importance.

Building audio-visual content (e.g. an educational video) around accessibility best practices from the start is recommended. This approach will provide a universal experience for all viewers and will give users a variety of ways to engage with cIRcle content. See W3C’s Audio Content and Video Content and Planning Audio and Video Media guides when beginning any multimedia content projects.

When audio-visual content is included, alternative formats for content engagement should be provided. These may include, but are not limited to:

• Alternative text
• Full text transcripts
• Synchronized and high-quality closed captions
• Description of visual information
• Sign language interpretation

The link for the alternative formats should be placed immediately next to the non-text content in the Wiki page or in the body of the object element itself.

Alternative Text (Alt Text)

Adding helpful alt text to images makes their meaning clear for people who may not be able to see or otherwise understand the image. It is important to create alt text that speaks to the image’s meaning within a specific Wiki page. Alt text will not appear visually on your Wiki page, and is not equivalent to a caption.

Alt text should be added to all non-text-based visual elements that convey information or meaning, including images, buttons, icons, etc.

To create meaningful alt text, it should:

• Aim to answer the question: “What is the information or meaning conveyed by the image in this particular context?”
• Use plain, concise language (under 140 words) with normal punctuation
• For complex images, provide both a short and a long description

The effectiveness of your alt text can be tested using the Web Accessibility Evaluation Tool (WAVE).

cIRcle Screenshot Guidelines

When to use screenshots

Screenshots can be used to enhance text and to support visual learning. Screenshots are widely used in cIRcle’s User Guides. In any page, the text must present all relevant information for the user, including steps and actions to complete processes and any information presented visually in the screenshots. Screenshots should be considered a secondary information source.

You may use screenshots to:

• Instruct users in how to complete multi-step processes
• Highlight new features you want to emphasize

What to capture in a screenshot

When determining what to capture in a screenshot, the key feature should be the focal point, with surrounding features that show how to "get there" (e.g. showing tool bar with a drop down list, which includes your key feature).

Avoid capturing the full screen / website interface if it is not relevant to the current feature.

Tip! If your screenshot includes linked text, clear your browser history before capturing your screenshot. This will ensure that all linked text shows up as blue rather than purple (indicating you've previously clicked the link).

Screenshot specifications

File format: PNG (.png) is the recommended screenshot file format for cIRcle. It offers high quality resolution and captures many colour options.

File size: The maximum file size for upload to UBC Wiki is 20 MB. PNG results in large file sizes (which can result in long loading time for users), so files may need to be resized prior to uploading to UBC Wiki.

Screenshot dimensions: Screenshots should be resized before adding any annotations (shapes, text) or uploading the files to UBC Wiki. For ideal website performance, screenshots being uploaded to UBC Wiki should have the following image dimensions:

• Image width: 700px
• Image height: may vary, depending on the necessary content captured within the screenshot

Exception! If your screenshot is focused on a small section of the screen, a reduced image width may be appropriate. If your screenshot width is smaller than 700px after capture, maintain the width as-is. Consult with your cIRcle Office Project Manager as-needed.

Creating a screenshot

1. Using Snip & Sketch, create a new screenshot capture. Crop the capture as needed, then save the capture as a PNG.
2. Paint 3D is the primary tool recommended for resizing screenshots and basic screenshot editing/annotation.
   1. Resize your screenshot capture:
      1. Open original screenshot file: Menu > Open > Browse files
      2. Ensure the view size is set to 100%
      3. Resize image: Canvas > Resize canvas:
         • Ensure 'Lock aspect ratio' and 'Resize image with canvas' are both checked
         • Set width to 700px or smaller, as appropriate
   2. Annotate your screenshot capture.
      1. Select annotations from 2D shapes.
      2. After placing a shape or text, adjust the line thickness, colour, and placement. See Annotating a screenshot for more detailed instructions.
         • Note: Annotations cannot be moved after being placed on an image. To adjust an annotation, use the Undo option or History to remove the annotation.
   3. Save your screenshot capture with all annotations as a new PNG file. This will maintain the original for any subsequent adjustments.
      1. Menu > Save as > Image > set 'Save as type' as PNG.
      2. Name your annotated screenshot following the naming convention identified in Uploading and Using Audio-Visual Content.

Annotating a screenshot

Annotations may be used on a screenshot to visually highlight a certain feature or button, or to provide additional guidance on sequential processes. If the annotations provide guidance or contextual information that is not captured in the body text, the annotations must be adequately described within the screenshot’s alt text.

Before adding annotations to a screenshot, ensure that the file has the appropriate dimensions (see Screenshot specifications). Screenshots for cIRcle pages may include shapes, text, or a combination of both.

Shapes: A mix of boxes and arrows can be used to annotate screenshots, using the following broad principles:

• Shapes are contingent on the pre-existing design and elements of the background image being annotated and what is being conveyed to users.
• Boxes are the preferred annotation shape. Boxes are used to:
  • Indicate a required user action (such as selecting a button or link)
  • Highlight a specific feature or area within a screenshot (such as a particular paragraph on a UBC Wiki page)
• Arrows can be used:
  • In addition to boxes to highlight areas that are relatively small on the screen
  • On their own when the feature would benefit from expanded instruction (e.g. “See tip” arrows).
• Additional shapes (e.g. ‘X’) may be used if they are relevant to the instruction.
• Placement of shapes should aim to not obscure relevant areas of the screen for the current task-at-hand but may be placed over non-relevant areas.
  • Boxes should aim to be placed around the relevant action (e.g. a button/link) but may be slightly expanded if the box will obscure relevant areas/text.
  • Arrows should clearly point to the item of-interest as it pertains to the instructional text (e.g. a field name).
• Arrows should remain level (not angled) and can be directed in any direction (up, down, left, right).

The recommended shape properties for annotations in Paint 3D are:

• Line thickness: 5px
• Line colour: Medium green (HEX code #0ed145; RGB (14, 209, 69))
  • Green provides high contrast on numerous cIRcle webpages (as opposed to blue or yellow).
  • People with various types of colour-blindness will see each page differently.
    • It is recommended to test visual legibility for colour-blind people: use Colblindor’s Coblis — Color Blindness Simulator to upload and test your annotated screenshot.
    • The placement of shape annotations over background colours may be adjusted slightly to improve the contrast ratio for users with standard and irregular vision.
  • It is recommended to avoid using colours in the red colour family to try to convey information importance or instructions which contrast with those in green annotations (e.g., green symbolizing a ‘correct‘ method, and red symbolizing an ‘incorrect’ one).
• Fill colour: White (HEX code #FFFFFF) or transparent

Text: It is recommended to use a sans serif font with adequate “breathing room” between letters (i.e. letters are distinct from one-another).  The recommended font properties for annotations are:

• Font: Arial, with bold
  • Calibri is a secondary option
• Size: 12 pt
• Colour: Black (HEX code #000000)

Generally, these fonts should be placed within boxes/arrows with green outlines and a white fill colour to ensure they stand out & are clearly identified as annotations.

Uploading and Using Audio-Visual Content

When adding audio-visual content to your Wiki page, it must first be uploaded to UBC Wiki as an independent file through the Upload Wizard. The Upload Wizard only supports images (.png, .jpg), PowerPoint (.ppt, .pptx), and PDF files. Multimedia files may be embedded into a Wiki page from another service like YouTube or Kaltura.

When uploading files to UBC Wiki, use the following naming convention:

[YYYY-MM-DD_Wiki_Page_Section_01]

For example: 2024-01-30_ETD_Guide_Register_01

Important! During upload through the Upload Wizard, you will identify the copyright status of the file, including assigning a Creative Commons license or attributing copyright to the file’s creator. If the file you are using is under copyright, be sure to have the author’s information and source of the file available during upload.

Screenshot placement

Once your screenshot has been added to UBC Wiki, it can be inserted into a page by using the Insert > Images and Media option in the Formatting Toolbar. See Adding Media/Images and Pictures for more detailed instructions on inserting files into your page.

Screenshots may be edited using the Edit > Media settings option. The recommended image display and placement properties for screenshots are:

• Caption: No caption.
• Alternative text: All images in a Wiki guide must have Alt text. Alt text for an image should be added after the image has been placed on the page to ensure that the alt text is appropriate and applicable to the image’s purpose and placement on the page. See Alternative Text (Alt Text) for more information about creating alt text.
  • After an image is already inserted into the Wiki page, select the inserted image, click ‘Edit’ and add alt text to the Alternative text field in the ‘Media settings’ pop-up window, then click ‘Apply Changes’
• Position: No text wrapping, no alignment specified
• Image type: Frameless, no border
• Image size: Custom, 700 x [variable] px

Information in the Wiki page, including body text and screenshots, should be presented chronologically.  Screenshots should be inserted as closely as possible to the relevant part of the main body text which describes them.  

Most screen readers read information top to bottom and left to right. Screenshots should be presented prior to text indicating a final action (e.g., "When you have finished, select "Next" to continue.”), which should be the last element in the instructional page or page section.

---