Avenue to Learn Support Style Guide

Avenue to Learn Support Documentation Style Guide

A few caveats: this documentation was written for our own internal documentation team to write for this Avenue Help site. It presumes that you’re using a web page to document how to do something. The reason we like websites for documentation is that the website is up-to-date. You, as the document designer are always in control of what is said at the moment, and aren’t having to track down old, out-of-date documentation that has circulated out of your control. While this document is for our own documentation (and you can see where we have not adhered to it!) we thought it would be useful to share beyond our own walls to share what we do. If you want to adopt these ideas, great! If you’re doing something that we’re not, and it’s something we should be doing, let us know!

While standardization is important for a functioning knowledge base, we’re human. Try to make other’s pages better where you notice a missing alt tag, caption or a list that’s unnumbered. Do a search before you post, just to ensure you’re not covering something that is already there.

Tagging: All articles should be tagged. There is a standard lexicon for the tags, but feel free to add additional tags if they don’t exist. Think of what someone might be searching for when tagging. Tagging assists in the related pages, be judicious in using “assignment” as a tag as there is Assignment Folders, a specific tool within Avenue.  When in doubt, over tag, and we will sort it out as we go along.

Avenue to Learn: When referring to Avenue to Learn, please use the full name, or Avenue if you must shorten. A2L, and any of the many variants are not to appear on MI documentation. The reason for this is that the name was selected from a number of submissions and it is important to honor that decision. There’s also some other reasons why Avenue to Learn over any of the other shorthand: A Venue to Learn and Avenue to Learn – that dual meaning is one of the reasons the name was selected. Additionally, if you are using A2L, that shortening is a reference to the company, D2L, who used to be called Desire2Learn. The product that they sell, is not called D2L however, it’s called Brightspace, so A2L is a shorthand reference to a product that doesn’t go by that name.

Sequential Instructions: Where you have a series of steps or tasks, please use numbered lists where possible.

Videos: Embedded videos are preferred. Identify Brightspace vendor videos clearly. Identify and credit the author of videos in some supporting text. All videos must be captioned, no matter who created them. If the video is not captioned, find an alternative.

Headers: For accessibility and screen reader optimization (which also makes content searchable), use H1 for the title of the page, and do not skip headers. All subheadings should be H2, and subsequent headings should be H3 (if needed). If you need more that two headings on a page, consider breaking the content into smaller chunks.

General Accessibility: Check with WebAim tool https://wave.webaim.org/

Images: All images should be captioned and provide an alternative description and ALT tagged where possible. When creating images, use a red single headed arrow to indicate where one might look on the image if necessary. Do not use drop shadow on the whole image, or the torn page look. Simple cropping as much as possible.

Language: Avoid using contractions (it’s, don’t). Maintain proper noun usage (capitalize proper nouns). Try to make all language used as simple as possible. Try to avoid abbreviations and contractions. If you do need to use acronyms – either spell out what the acronym stands for or explain what the acronym means the first time on the page. For instance, with ASCII, it does not always make sense to explain it stands for American Standard Code for Information Interchange – rather explain what it means (a code that allows multiple computer systems to display the same character).

Bolding: Typically when talking about a tool within Avenue to Learn, we will bold the word and capitalize the first letter of each word in the tool name. Subsequent uses of the the tool name will follow normal language rules (tools are proper nouns!). Additionally, bolding can be used to draw attention in sequential instructions to the thing you are supposed to click, or task you are doing. Try to be judicious, and not over use bolding as it will become less effective.

UPDATE PAGES

These pages (eg. July 2020) are essentially culled from the official Brightspace Monthly (posted on Brightspace Community) released notes, and edited down to what impacts instructors and students. Typically, we announce our own updates (authentication, new tools, etc) in these announcements as well. Jon, Daryl, or Josh will craft these.

  • H1 Title
  • H2 subheaders (migrate to H2 if they are H3)
  • Text paste in from Brightspace documentation
  • Alter language to reflect local context
  • Images, download, rename upload, make accessible
  • Tag with tool names that were updated this month

FAQ PAGES

FAQ is the category for frequently asked questions or that people suggest that we should have. Typically this FAQ will answer one question about one tool. If the process spans two or more tools, either break the FAQ into two questions and link to the second part at the end of the first part (eg. how to use the Quiz Question Converter) or consider a Tutorial.

  • H1 Title (only capitalize proper noun, and tools within Avenue): use the question  (eg. How do I enroll students into my course?)
  • H2 headers (migrate to H2 if they are H3)
  • Text paste in from Brightspace documentation/ticket/predefined reply
  • Numbered steps (do not use numbered list)
  • Images, download, rename, upload, make accessible
  • Tag with tool names, and the sort of language that people might use to search for (eg. enrol, enroll, CSV enroll, adding students, adding students to a course, Classlist, etc. for an article on how to enrol students into a course on Avenue)

TUTORIAL PAGES

Tutorials are the catch-all for our self-directed workshop versions, as well as specific tasks that span two or more tools in Avenue to Learn (such as using groups to deliver two or more different exams during the same time period).

  • H1 Title (only capitalize proper noun, and tools within Avenue): this is a statement (eg. Using Groups to deliver different midterms to your class)
  • H2 headers (migrate to H2 if they are H3)
  • Text paste in from Brightspace documentation/ticket/predefined reply
  • Numbered steps (do not use numbered list)
  • Images, download, rename, upload, make accessible
  • Tag with tool names, and the sort of language that people might use to search for (eg. enrol, enroll, CSV enroll, adding students, adding students to a course, Classlist, etc. for an article on how to enrol students into a course on Avenue)

 

Related Articles