Documentation:OpenUBC/POSE/StyleGuide

From UBC Wiki
Ambox warning yellow.png This article is still being drafted. This means that the article is still being worked on and information may be incomplete. This template will be removed when the article is finished. If you have any concerns, please start a discussion on the talk page.

The following is a style guide for creating the POSE modules.

Colours

Learning Pathways

  • Open Education - Purple (#9C9CFF) and Black (#000000)
  • Open Access - Blue (#4BBEEC) and Black (#000000)
  • Open Research - Teal (#60D69E) and Black (#000000)
  • Undeclared - Green (#C6E86F) and Black (#000000)

Text Formatting

  • Body text should be "normal" or "regular" style.
  • Use bold sparingly. Instead use better writing to emphasize your points.
  • Never use ALL CAPS or underline text (except for links).
  • Use italics only to serve a purpose (e.g. quotations, citation formatting).
  • Use just one space after a period, not two.

Bullets

  • Only use numbered lists for steps in a process
  • Use bullets for all other lists

Acronyms and Abbreviations

  • If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it with the acronym in brackets. Then use the short version for all other references.
    • First use: Coordinated Universal Time (UTC)
    • Second use: UTC

Numbers & Dates

  • Spell out numbers ten and under and a number when it begins a sentence. Use numerals for numbers greater than ten
  • Spell out the day of the week and abbreviate the month, unless you’re just referring to the month or the month and the year.
    • Saturday, Jan. 24, 2015
    • January 2015
    • Do not use ordinals indeed (e.g. January 24th)

Ampersands and Other Special Characters

Use ampersands in page titles and headings. Avoid ampersands in body copy—spell out "and" instead

Writing Style

  • Use contractions to set a familiar tone (e.g. you’re, it’s, etc.)
  • Vary the format or rhythm – include audio or video when appropriate.
  • Make it relevant – ask a question, include a quote, an example or a narrative.
  • Include images, diagrams and other visuals that support the text.
  • Avoid redundancy; however, strategic repetition can be a helpful memory aid.
  • Separate individual concepts, processes, etc. visually and limit each segment to approximately 200 words.
  • Use familiar words and avoid the use of jargon and contractions.
  • Compose sentences in active, rather than passive, voice using strong verbs. Be clear about who is doing the action.
  • When describing an action or task that has a natural order or sequence, structure the content so that the sequence is obvious and consistent.
  • Make chronology clear (See: Bullets). If emphasis is required, try to convey the emphasis through clear expression rather than highlighted text.
  • If highlighted text is desired, avoid excessive use of bolding.
  • Do not use italics (they are hard to read on screen) .
  • Do not underline (it can be confused with a hyperlink).
  • Reserve quotation marks for citations and dialogue.

Tone

https://ualibraries.gitbook.io/ua-libraries-editorial-style-guide/chapter1

Media

Images

  • Provide ALT Text for all images
  • Use CC licensed images
  • Attribute the images directly underneath the image using the TASL method

Videos

  • Provide ALT Text for all Videos
  • Attribute the images directly underneath the video using the TASL method

Adaption Statements

  • If you have used content from external openly licensed resources, the adaption/attribution statements should be listed at the end of the module
  • The statements should come under the title: Attribution Statements
  • The statements should follow this structure:

Structure of the Modules

The modules should be organized in the following way:

1. Big Ideas

  • Question(s) for participants to ask themselves before stepping through the module content.
  • The question(s) should be a big reflective statement on why the issue matters globally
  • Up to 2 additional sentences that provide context to the question.

2. Outcomes

  • Under 5 bulleted statements of what the participants should expect to come away with upon completing the module

3. Why it matters to you

  • A paragraph of no more than 3-5 sentences that outlines how the module with empower the participants to apply what they’ve learned

4. Practice / in practice

4.1 Assignment

Assignments are integrated into core module content and should bring together concepts introduced through the module.

4.2 Challenge Bank Structure
  • Up to 5 sentences outlining the specific objectives the participant needs to complete.
  • Up to 3 links to resources required to complete the challenge
  • Provide an example of a completed challenge to promote understanding of effort and time expected to complete the challenge.

Challenges in the challenge bank do not have to be integrated into the main content of the module and can be bonus to the main assignments.

4.3 Reflect

  • Can be a reflection on their own engagement or practice or a reflection on the challenges or over all plan for action (how does it relate or not relate to your practice)
    • E.g. Think back to a time ...
  • Self guided and personal and does not require sharing

5. References

  • Use APA style for references
  • Provide a permanent URL to the object

6. Additional Resources

  • Under 5 bulleted additional resources
  • Use APA style for references
  • Provide a permanent URL to the object

Resources on Style

  • https://www.cu.edu/sites/default/files/eld-style-guide.pdf
  • https://ualibraries.gitbook.io/ua-libraries-editorial-style-guide