Markdown Style Guide for Shadow Academy Course Notes

Generic Guidelines

Section names and numbering

Section names should clearly describe what the section is about. The first sections should be named "Introduction" and the last section should be named "Conclusion."

Section headers should be numbered for easy reference following this scheme:

1 - Introduction
2 - Example Section 1
3 - Example Section 2
  3.a - Example Sub-Section 1
  3.b - Example Sub-Section 3

Third level sections should be avoided where possible. An alternative is to use quasi headings, which are italicized, under second level headings.

Point of view and tone

Like on a Wiki, all course note should. as much as possible, be of a neutral point of view. They should give facts, and if opinions are needed they should be balanced and from multiple "angles."

Courses about "in-universe" topics should be written in the past tense.

Any "out of character" courses, such as tutorials on using computer software, should be written in the present tense.

Spelling and grammar

Spelling mistakes and obvious grammatical errors can be jarring for readers. It also distracts from the professionalism of a document. English is not everyone's first language, so it is understandable that it is not easy for everyone to produce Course Notes that are 100% accurate, however at a minimum all notes should be run through a document processor like Microsoft Word and checked for spelling and grammar errors.

If possible, someone well versed in the English Language, and its nuances, should read over notes before they are made public.

Sex appeal, know when to break the Markdown Guidelines

While these guidelines set out to standardize how course notes are presented and "marked up," it is important to realize that these rules should not be followed to the letter in all cases.

If following these guidelines would make the notes look awkward, ugly or otherwise hard to read, they should be adjusted to give the student the best possible reading experience.

If you are ever unsure, ask a fellow faculty member or the Headmaster.