Style guide

From WikiEducator
Jump to: navigation, search


Road Works.svg Work in progress, expect frequent changes. Help and feedback is welcome. See discussion page. Road Works.svg

Outdated page. Guidelines now replaced with DS4OER course materials. Page kept for historical reasons.

Major update in progress for OERu MVP ...


Guidelines for sub-elements of an OERu course

  • This guideline aims to promote consistency of language for OERu courses.
  • OERu courses will be subdivided into Units
  • Where possible, courses should not include more than three hierarchical levels
  • The preferred nomenclature is Course --> Unit --> (Free choice for naming of this level, eg section, lesson, study unit, etc)
  • Developers will have flexibility regarding preferred naming conventions for additional sub-levels, for example, sub-section, but should be used consistently within the specific course.
Note: These guidelines were adopted based on the recommendations of a rough consensus poll.

Guidelines for acknowledging original course contributors

(Comment.gif: This needs updating to agree a standard convention for acknowledging sources of remixed courses. Do we need a template? Perhaps a standard "credits" page in the course guide is needed. --Mackiwg (talk) 06:09, 7 April 2016 (UTC))

  • When uploading learning materials for the first time in WikiEducator, the copyright of the original rights holder must be acknowledged in the comment summary box before saving the page. For example: Copyright: OER Foundation, under CC-BY license. Source: http://oerfoundation.org/files/OERu/OERu2011-11_Report-A.pdf . This should appear as the first edit comment on the relevant history page.
  • Copyright acknowledgement must be done in accordance with the requirements of the respective copyright license.
  • In the absence of this copyright acknowledgment, the page may be deleted without notice.
  • Where the original contributor (first person creating the page) has omitted this copyright acknowledgment, they should make an insignificant edit, for example adding a space and inserting the copyright acknowledgement in the edit comment which will appear on the history of the relevant page.
  • Each OERu course resource (a collection of pages) will contain a copyright page as a subpage of the respective collection acknowledging the original contributors and license. The copyright page must include a clear statement that subsequent versions are enhanced by the WikiEducator community. For consistency and the possible inclusion of machine-readable metadata, we recommend the use of Template:OERu_Copyright. For example:
  • The OER Foundation, on behalf of the OERTen, will list the OERu courses and their original contributors on a public website.
  • Course developers should not include institutional logos of the original contributors on OERu course pages or navigation templates.

Guidelines for course components

Course guide

  • Each OERu course should develop a generic introductory resource called a Course guide
  • The Course guide should include a course overview, outcomes, list of resources and assignments.
  • To facilitate reuse across the OERu network, the Course guide should not include institution specific information, for example, university contact numbers. These will be provided by the respective institutions who decide to reuse OERu courses locally.
  • OERu partners are free to develop their own custom assessments. In cases where partners choose not to use the original assessments, they take responsibility for developing the customised assessments. (As a wiki, customised assessment pages can be incorporated into unique course collections for individual institutions.)

Community-based question and answer forum

  • The OERu 2012 prototype courses will trial AskBot as a question and answer database for content specific and general student support.
  • Further detail to be developed the wiki way.

Guidelines for layout and semantic markup of wiki course pages

Avoid common markup mistakes

Don't use bold for styling headings and subheadings
Use heading styles and levels to format headings. The toolbar for numbered and bullet lists should be used for formatting lists. For more information consult the VisualEditor userguide.
A common mistake made by new authors is to use bold for signifying headings. This is problematic because the HTML produced will not differentiate headings from normal text using the bold attribute. Moreover, the wiki will not be able to generate an automatic table of contents based on the hierarchy of headings. Also, when exporting wiki pages for different stylesheets, the conversion script will not be able to apply the target heading styles. Editors should always use the heading style option for headings and subheadings.
Linking internal WikiEducator pages incorrectly as external page links
The wiki differentiates between internal links (a link to another page in WikiEducator) and external links (a link to another website.) Internal and external links are displayed differently. For example, this link to Google displays a small arrow graphic whereas this link to the WikiEducator homepage does not display the arrow graphic after the link. When linking to an external page using VisualEditor type the full url in the link field, for example: "http://www.google.com". Do not use the full url for internal links. Internal links should only use the page title, that is the text which appears after the url prefix: "http://wikieducator.org/". For example, if you want to insert a link to the OERu planning page in WikiEducator (which is found at: "http://wikieducator.org/OERu/Home") you should only enter "OERu/Home" in the text field (don't include the "http://wikieducator.org/" prefix.)
Not applying the correct style for lists
Numbered lists and bullet lists should be styled using the toolbar for numbered or bullet lists in VisualEditor. A common mistake is to cut and paste lists from other sources and forgetting to apply the local wiki style for lists, or attempting to generate numbered lists by typing numbers. This is not advised, because this removes automatic numbering and will generate additional work to renumber the list in the event that a new bullet is inserted into the sequence.

Images

  • Images should be placed in a frame or thumbnail
  • Captions should be used within the frame or thumbnail
  • Metadata relating to attribution, license, source etc. should be included on the image page (not on the content page).
  • Layout considerations taking into account different screen sizes for viewing content and print-versions of the pages
    • Avoid placing images directly after each other - -separate with text
    • When using photos or images and aligning these left or right, we recommend an image size of 350 - 400 pixels, unless the context justifies a smaller or larger image. Larger images should be centered on the page.)
  • Before uploading a new image to WikiEducator, consider searching and using an image from commons.wikimedia.org, as these images are fully documented as to attribution, license, source, etc. and easy to add to any page on WikiEducator (see using an image from Wikimedia Commons). And of course you are encouraged to upload openly copyrighted images to commons.wikimedia as a way to "share the wealth" (upload instructions).

Language

Capitalisation

Consistent with standard practice, capitalise the initial letters of proper names, except where common practice suggests otherwise, and write common nouns in lowercase letters. Some specifics:

  • Write open educational resources in lowercase letters, when the term is used to describe a type of learning resource.

Spelling (English language locale)

  1. Consistency within a course takes precedence over locale preferences (i.e. English spelling for United States, United Kingdom, Canada, Australia, New Zealand etc.)
  2. Use the preferred spelling of the location of the primary OERu assessing institution. For example if the primary assessing institution is based in the US, use US spelling consistently for the course. Where assessing institutions are from different regions, the course team should agree the spelling convention and specify this in the course blueprint.
  3. When in doubt as to customary spelling, be consistent. Consistent spelling contributes to the professional look and feel of the finished course.
  4. Consult the spelling comparison chart for guidance.

Titles

Enclose titles of short videos, or other short creative works in quotations.

Abbreviations

  1. Abbreviations should be written out in the first instance of the course.
  2. We recommend the inclusion of a course glossary in the course guide.

Citations/References

Use clickable endnote citations, using wiki code positioned adjacent to the referent text: <ref>citation details</ref>, rather than in-text parenthetical citations, for example (author, year).

Locate endnote citations (using the code <references/> in a section called "Notes" (level 2 header) at the end of the page.

Use APA style for citations (see the APA Formatting and Style Guide section in the OWL Purdue Online Writing Lab for specifics) with the following exceptions:

  • As indicated above, use endnotes for citations, rather than in-text citations with an associated reference list. We prefer this due to the ease of coding and using endotes in WikiEducator.
  • Use an external link to the original work, for example with the title of the work, rather than including the full url at the end of the citation.
  • Format dates as dd monthname yyyy, (e.g., 30 January 2011), including as much of the information as available. If date is unknown, use "No Date".
  • If a reference work is a web page or wiki page without a specific date of publication, include the date the information was retrieved at the end of the citation (e.g., Retrieved 30 January 2011).

Editorial checklist

  1. Check the discussion tab for any outstanding or unresolved issues.
  2. Ensure that all internal links use the wiki syntax for internal links (i.e.[[Foo/subpage|Pipe]] and not [http://wikieducator.org/Foo/subpage Pipe])
  3. Check each image for proper metadata and license information, and verify the license at the source especially incorrect Creative Commons licenses, for example: re-licensing a CC-BY-NC-SA image as CC-BY in WikiEducator.