This site is a Wiki. Please feel free to update, edit or comment on any page via the "edit" and "discussion" tabs above.

Sakai:Style Guide

From Information about Isaak, Brock University's Sakai-Based LMS

Jump to: navigation, search

These Wiki articles are primarily "howto" articles containing instructions on using Isaak, Brock University's Sakai-Based LMS. Most articles are focused toward instructors, as they have the most responsibility inside Isaak, Brock University's Sakai-Based LMS, however some articles are focused on students.

Please note that most style guides are appreciated but few are required. We assume good-faith with all wiki contributions and appreciate every contribution.

Contents

[edit] Important Style Considerations

[edit] Language Style

Articles should use plain English, avoiding use of technical terms where possible. Where technical terms are used, they should be defined (either directly or indirectly by linking to appropriate articles or pages).

Articles should be written from a third person point of view. That is, never refer to "I" or "me". Instead refer to the person reading the article as "you" or by role or title.

[edit] Page Style

Articles should be plain, using markup where appropriate. The purpose of the wiki is to provide instructions, not look beautiful. Images should not be used to decorate or stylize articles.

Wherever possible you are encouraged to use lists.

[edit] Format

Articles should contain the items listed here, in the order that they appear.

  • Begin with a summary of the article subject.
  • Provide a section on troubleshooting if appropriate - this section may contain common problems or errors encountered and how to fix them.
  • List any related articles, even if they have been linked within the article itself. This list can include articles from other sites.
  • Make sure you use the appropriate templates
  • Make sure you tag the article with the appropriate categories (See Sakai:Style Guide#Categories).

[edit] Describing the Sakai Interface

  • Field labels, clickable links or drop-down list choices that appear on Isaak, Brock University's Sakai-Based LMS screens should appear as bold
  • Messages - Informational, error or warning messages are separated from the text using the italics i.e.: Warning: You are about to delete important information...

[edit] Discussion

Discussion of any kind should appear on the articles discussion page, not in the article itself. All constructive criticism is welcome, however please note that the discussion pages are not good places to ask for help.

[edit] Headings

Headings use the standard Mediawiki convention and start at == (not =).

[edit] Categories

  • Categories ([[Category:Foo]]) should be at the end of articles. All articles should be in at least 1 category.
  • Be sure to include the categories of Instructors, Students and Help where appropriate

[edit] Isaak vs. Sakai

  • Please refer to what user will experience as part of Isaak
  • Anything that is Brock University should be referred to as part of Isaak
  • Limitations, results of Design decisions and bugs should be referred to as part of Sakai or the Sakai Project


[edit] Roles (technical and professional)

  • Instructors is used to refer to teachers, faculty, contract-faculty, teaching TAs, etc. When writing instructions it is far more useful to ask that a message be sent to "the instructor" than including the instructor's name.

[edit] Appreciated Style Considerations

[edit] Citation style

Please See http://en.wikipedia.org/wiki/Cite_your_sources

[edit] Free link style

The use of so-called "free links" to other topics, for example, [[George W. Bush]], is encouraged. Use the links for all words and terms that appear in your article for which it could be worthwhile to read the linked article. However, don't overdo it. Do not link every occurrence of a word; simply linking the first time the word appears will usually be enough. (This guideline has yet to be discussed for Wikiquote — some feel that it may not be appropriate in the middle of quotations.)

Links that follow the Wikipedia naming conventions are much more likely to lead to existing articles, and, if there is not yet an article about that subject, will make the creation of a correctly-named article much easier for later writers.

It is possible to link words that are not exactly the same as the linked article title, [[English language|English]] for example. Make sure however that it is still clear what the link refers without having to follow the link. When making plurals, do [[language]]s. This is clearer to read in wiki form than [[language|languages]] — and easier to type.

Try to link accurately. If an article you want to link doesn't yet exist, do a quick search to find out if that is really the case; the article may be named slightly different from what you expected.

[edit] "See also" styles

Informal references to related articles that have not been linked from free links in the text are best handled by "See also:", e.g.

See also: Internet troll, flaming

Sometimes it may be useful to have an explicit cross-reference in the text, for example, when a long section of text has been moved somewhere else. In these cases, please make the link bold so that its significance is easier to recognize.

[edit] HTML elements

The software that this wiki runs on, Mediwiki does not support HTML abbreviation elements (<acronym> or <abbr>); therefore, these tags are not inserted into the source.

You may use <div> </div> tags accompanied with style tags to assist with layout. This is generally the only HTML markup allowed.


[edit] Numbers

[edit] When to Spell Out a Number

Rules for using Arabic numerals or spelling out numbers are as follows and are listed from highest priority to lowest.

  • If the number is part of a casual expression, spell it out.
  • If the number is a calendar year, do not spell it out.
  • If the number is an age or percentage, do not spell it out.
  • If the number begins a sentence, spell it out. Awkward sentences should be reformed.
  • If the number is greater than 10, do not spell it out.
  • If the number is one through nine, spell it out.

[edit] Cardinal Numbers and Ordinal Numbers

  • Cardinal numbers include figures 1, 2, 10, 101, and so on, and the corresponding words.
  • Ordinal numbers include the terms 1st, 2nd, 10th, 101st, and so on, and the corresponding words.

[edit] Large Numbers

  • When spelling out large numbers, connect words ending in 'y' to subsequent words within the same number with a hyphen.
  • Avoid commas between words that are part of one number.
twenty-one
one hundred thirty-one
twenty-five thousand one hundred thirty-one
ninety bottles

[edit] Proper Names

  • Write proper names according to the owner's practice.

[edit] Abbreviations

[edit] Academic Degrees

  • Avoid abbreviating degrees.
  • Use an apostrophe in bachelor's degree, master's, etc.
  • Do not use an apostrophe in Bachelor of Arts, Master of Science, etc.
  • Use abbreviations only when the preferred method would be cumbersome.
  • Use abbreviations only after a full name.
  • Set abbreviations apart with commas.

[edit] Dates

  • Spell out days of the week and separate them from dates using a comma.
  • When listing a day, month and year, use ISO 8601 dates (YYYY-MM-DD).
  • When listing a day and month:
  • List the day first.
  • Spell out the day.
  • Set the day and month apart with "of."
  • Spell out the month.
  • When listing a month and year:
  • List the month first.
  • Spell out the month.
  • Set the month and year apart with "of."
  • Use Arabic numerals for the year.
Sunday, 2000-01-01
2000-01-01
The first of January
January of 2000

[edit] Times

  • Use 24-hour time formats.
  • Always use figures.
  • Follow absolute times with a timezone specification.
  • Separate days, hours, minutes and seconds with a colon and no spaces.
1:15:00:00.50 (1 day, 15 hours, 0 minutes, 0 seconds and 50/100 of one second)
15:00 minutes (15 minutes)
15:30 hours (15 hours and 30 minutes)

[edit] Titles

  • Avoid punctuation in titles, with the exception of hyphens.
  • Avoid abbreviations in titles. Spell words out and introduce abbreviations in the body text.

[edit] Units of Measurement

  • Metric units are preferred.
  • Use the prefixes published by the International Electrotechnical Commission (IEC) as part of IEC 60027-2 A.2 to express quantities of binary data.
Personal tools
  • Log in / create account
Bookmark and Share