Documentation:CTLT Resources/TLPD/Working Guidelines for Resource Development on UBC Wiki/Style Guide

From UBC Wiki
Jump to navigation Jump to search

 In this style guide, we are talking about how to make page as read as standalone pages. 

Content overview

When you create a resource on the wiki, the best practice is to make sure the resources can be read as standalone pages. (i.e. It does not require a pre-requisite for the readers to understand the resource)

Headings & Subheadings

Whenever the resource is too long, you can add headings and subheadings to organize your content. Headings are like chapters in the book. It makes information easier to read and digest. It also makes the content more accessible, especially to those who are using screen reader applications. Headings should be descriptive, concise and in a consistent order.

Hierarchy of headings

Headings have a hierarchy. The title of the page will be the first heading . The sub-topic of the title of the page will be the "Headings" . The sub-topic of the "Headings" will be "Sub-heading 1". The sub-topic of Sub-heading 1 will be "Sub-heading2" and so on..

If I use this page as an example:

  • "Style Guide" will be the first heading, or in the other words, the title of the page.
  • Content Overview, and Headings & Subheadings will be Headings because it is a sub-topic of "Style Guide".
  • "Hierarchy of headings" and "Headings&Sub-headings title" will be Sub-headings 2 under "Heading&Subheadings" Headings because "Hierarchy of headings" and "Headings&Sub-headings title" are sub-topic of "Headings & Subheadings"

Headings & Sub-headings titles

Heading and sub-headings titles should be descriptive and concise. They are like a short summary of the section you are about to write so headings should be relevant to the content of the section. Avoid jargons and long titles.

For example:

  • "Chapter 1" = The heading is concise but It does not really tell what the section is about.
  • "Headings and Subheadings need to be in hierarchy " = It is descriptive and tells what the section is about, but it can be more concise.
  • "Hierarchy of headings" = It is concise and descriptive so it works as a heading title.

Using Categories

Creating a category page

Using Infoboxes

Using an Infobox can be a useful way to organize your resources wiki. See Help:Infobox to learn how to create infobox in the wiki.

Using Mbox

When you want to highlight certain information, using an Mbox like:

This message box is using an invalid "type=growth" parameter and needs fixing.

You can learn how to use the template from Template:Mbox

Embedding multimedia content

You can embed multimedia content to your page including embedding YouTube videos, Google Slides, Prezi, etc. You can do so by inserting a widget to your page. See Help:Widgets to learn how to add a widget to your page.