|
|
Line 5: |
Line 5: |
| == Generic Guidelines == | | == Generic Guidelines == |
|
| |
|
| === Section names and numbering === | | === Section names === |
| Section names should ''clearly'' describe what the section is about. The first section should be named "Introduction" and the last section should be named "Conclusion." | | Section names should ''clearly'' describe what the section is about. Do not use "Introduction" as your first header since it provides no information about the topic of that section. Introductory text may be placed before the first header. |
| | |
| Section headers should be numbered for easy reference following this scheme:
| |
| | |
| <pre>1 - Introduction
| |
| 2 - Example Section 1
| |
| 3 - Example Section 2
| |
| 3.a - Example Sub-Section 1
| |
| 3.b - Example Sub-Section 2</pre>
| |
| | |
| 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 === | | === Point of view and tone === |
Line 26: |
Line 16: |
|
| |
|
| === Spelling and grammar === | | === 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. | | 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 or Google Docs 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. | | 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 === | | === 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. | | 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. |
|
| |
|
Line 50: |
Line 40: |
|
| |
|
| === Header levels === | | === Header levels === |
| Primary headings should be level 2 headers. They are achieved in Markdown as: | | Primary headings should be level 1 headers. They are achieved in Markdown as: |
|
| |
|
| <code>## 1 - Introduction</code> | | <code># First Heading</code> |
|
| |
|
| Secondary headings should be level 3 headers: | | Secondary headings should be level 2 headers: |
|
| |
|
| <code>### 3.a - Example Sub-Section 1</code> | | <code>## Example Sub-Section 1</code> |
|
| |
|
| Note that the number of "hashes" denote the level of the header. Like on the wiki, first level headers are too large and should be skipped in favor of second level headers. | | Note that the number of "hashes" denote the level of the header. |
|
| |
|
| === Lists === | | === Lists === |
Line 103: |
Line 93: |
|
| |
|
| === Images === | | === Images === |
| Images can either be linked directly into the body of the notes or given a name and linked to in a block at the end of the notes. In the interest of maximizing the readability of the course note's Markdown, it is preferred to list the url's to the images at the end of the notes.
| | In the interest of maximizing the readability of the course note's Markdown, images should be given a name and linked to in a block at the end of the notes. |
| | |
| Where you would like the image to appear in the notes, write an exclamation point, alt text in square brackets and an id name in square brackets.
| |
|
| |
|
| <code>![Alt text][id]</code> | | Where you would like the image to appear in the notes, write an exclamation point followed by the ID in square brackets. Ensure that your ID is not exactly the same as the name for a normal link in the course notes. For example, do not use <code>![stormtrooper]</code> as your image ID if you've already linked the word <code>[stormtrooper]</code> in the course notes. |
|
| |
|
| At the end of the notes, include the full path to the image, like so: | | At the end of the notes, include the full, secure (https) path to the image, like so: |
|
| |
|
| <code>[id]: url/to/image</code> | | <code>[id]: https://secureurl.com/image.png</code> |
|
| |
|
| Note that in both of those examples, the ID must match in order for the image to show. | | Note that in both of those examples, the ID must match in order for the image to show. |
|
| |
|
| === Hyperlinks === | | === Hyperlinks === |
| Hyperlinks are very similar to images, except that they are specified without an exclamation point in front of them. For the same reason as with images, their actual url's should be at the end of the document. | | Hyperlinks are very similar to images, except that they are specified without an exclamation point in front of them. For the same reason as with images, their actual urls should be at the end of the document. |
|
| |
|
| Where you would like the link to appear: | | Where you would like the link to appear: |
|
| |
|
| <code>[Display text][id]</code> | | <code>[Display text]</code> |
|
| |
|
| At the end of the notes, include the full path to the image, like so: | | At the end of the notes, include the full, secure (https) path to the image, like so: |
|
| |
|
| <code>[id]: url/to/page</code> | | <code>[Display text]: https://secureurl.com</code> |
|
| |
|
| Again, note that the IDs must match, they must also be unique. | | Again, note that the IDs must match, they must also be unique. |
Line 157: |
Line 145: |
| Often, one of the best ways to learn is to look at (and borrow from) other people's work. You can see the Markdown used in any other Shadow Academy course, by adding ".text" to the end of the URL. | | Often, one of the best ways to learn is to look at (and borrow from) other people's work. You can see the Markdown used in any other Shadow Academy course, by adding ".text" to the end of the URL. |
|
| |
|
| <code>http://staging.darkjedibrotherhood.com/shadow_academy/courses/28.text</code> | | <code>https://www.darkjedibrotherhood.com/shadow_academy/courses/172.text</code> |
|
| |
|
| If you're ever looking over notes and wondering how the author managed to do what they did, add that to the address and you'll be able to see exactly how it was done. | | If you're ever looking over notes and wondering how the author managed to do what they did, add that to the address and you'll be able to see exactly how it was done. |
This document is intended to be a guide for those writing Shadow Academy course notes and those who are readying them for inclusion on the Shadow Academy website (often the same person). This document will give an outline of how the course notes should be structured and how Markdown should be applied to them so they appear as intended on the Shadow Academy website.
This document is maintained by the Headmaster and Praetor to the Headmaster.
Generic Guidelines
Section names
Section names should clearly describe what the section is about. Do not use "Introduction" as your first header since it provides no information about the topic of that section. Introductory text may be placed before the first header.
Point of view and tone
Like on a Wiki, all course notes 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 or Google Docs 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.
Markdown Guidelines
Be comfortable with the syntax
Unlike other options, like HTML, Markdown is a very natural way of writing course notes. Notes that have been formatted with Markdown can be easily read in their own right as stand alone documents. Chances are you have already used Markdown on other websites (possibly without realizing it), and it is fairly similar to the syntax used on the DJB Wiki.
The external links section below contains a number of links that you can refer to familiarize yourself with Markdown.
You can't irreversibly break something
There is nothing you can do with Markdown that will break the website or the document itself. Don't be afraid to play around with the syntax to get the course notes exactly how you want them.
If all else fails we can always go right back to the original document and start again, or see if there is a different revision we can refer back to, but in most cases removing the offending Markdown syntax will fix any issues.
Primary headings should be level 1 headers. They are achieved in Markdown as:
# First Heading
Secondary headings should be level 2 headers:
## Example Sub-Section 1
Note that the number of "hashes" denote the level of the header.
Lists
*
, -
or +
can be used to denote and item in a "un-ordered" list. In course notes it is preferred to use *
, though it makes no difference to what is rendered for the students. For sake of consistency, there should always be one space (no more) between the symbol and the item in the list.
To create a sub item in a list, simply indent that line.
* First item
* Second item
* Sub item under second item
* Third item
Renders
- First item
- Second item
- Sub item under second item
- Third item
If an item spans multiple lines, they should be indented to match.
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
An item can even be multiple paragraphs. Simply add an extra line in between lines within the item.
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
Numbered lists are denoted by a number and a period (1.
), note that Markdown does not care what number you supply, it will display the correct number based on what is in the list. When writing your course notes however, please accurately label the items in a numbered list for the sake of readability of your Markdown.
1. First item
2. Second item
3. Third item
Renders
- First item
- Second item
- Third item
Images
In the interest of maximizing the readability of the course note's Markdown, images should be given a name and linked to in a block at the end of the notes.
Where you would like the image to appear in the notes, write an exclamation point followed by the ID in square brackets. Ensure that your ID is not exactly the same as the name for a normal link in the course notes. For example, do not use ![stormtrooper]
as your image ID if you've already linked the word [stormtrooper]
in the course notes.
At the end of the notes, include the full, secure (https) path to the image, like so:
[id]: https://secureurl.com/image.png
Note that in both of those examples, the ID must match in order for the image to show.
Hyperlinks
Hyperlinks are very similar to images, except that they are specified without an exclamation point in front of them. For the same reason as with images, their actual urls should be at the end of the document.
Where you would like the link to appear:
[Display text]
At the end of the notes, include the full, secure (https) path to the image, like so:
[Display text]: https://secureurl.com
Again, note that the IDs must match, they must also be unique.
Bold and italics
Bold and italicized text should be used sparingly to draw attention to important words or sentences.
To italicize text, put one *
on either side of the word or words.
The quick brown fox jumps over the *lazy* dog
The quick brown fox jumps over the lazy dog
To make text bold, use two *
's either side of the word or words.
The quick brown fox **jumps over the lazy dog**
The quick brown fox jumps over the lazy dog
Quote and code blocks
Where you need to display a quote, start the line with a right angle bracket.
> This is a quote.
Where you need to display a block of code, for example in a programming course, indent the line by four spaces or one tab (spaces are preferred):
This is normal text.
Write-Host "This is Code"
Cheat and steal
Often, one of the best ways to learn is to look at (and borrow from) other people's work. You can see the Markdown used in any other Shadow Academy course, by adding ".text" to the end of the URL.
https://www.darkjedibrotherhood.com/shadow_academy/courses/172.text
If you're ever looking over notes and wondering how the author managed to do what they did, add that to the address and you'll be able to see exactly how it was done.
External Links
Conclusion
I hope that this guide has been clear and understandable, if you notice any errors or sections that need expansion please let the Headmaster know.