Your writing style should be friendly and relaxed. We want to err away from "too academic" in our approach to topics. Feel free to use pronouns like "you" and "we" when writing.
It's easy to fall back on samples like <element>Content</element> when teaching, but we want to prevent our students from developing confusion over what's real in code samples and what's demonstrative. Make sure your code samples use only real elements, properties, attributes and methods. When recording screencasts, try to use code samples from live websites instead of writing ideal examples. We want to make sure our examples are a reflection of what "real code" looks like.
Everyone learns differently. When creating content, try to find opportunities to use new media types. Content with a variety of images, text blocks, code samples and screencasts will make a bigger impact on a larger audience.
Tables, charts, and lists are great ways to share data, but we prefer text over these more tabular methods of communication. Resist the urge to make everything a <ul> of methods or elements. Think about logical groupings and prefer friendly text to sterile data-driven discourse. If you find yourself nesting lists or needing raw HTML to chart a concept, stop and consider a graphic instead.
No one programs in a vacuum, so they shouldn't learn in one either. Provide copious footnotes linking to more comprehensive resources so students can dig deeper into topics they find interesting. Ensure any inline links give a good idea of where they point - we don't want to overwhelm students who get lost in the Internet weeds! These resources should be at an approachable level for our students - we want to challenge but not overwhelm them.
Learning proper syntax is an important part of any developer's education, but it's the core concepts beneath the syntax that separate high-quality programmers from "copy-paste coders". When introducing new concepts, try explaining their intention without code first. We do need to teach syntax, but introducing our students to the abstract concepts that make up the foundations of software will help prepare them for a future in programming regardless of the "flavor of the week" language or framework.
Don't be afraid to share popular opinions or "best" practices, but be sure to provide a reliable source supporting them with a footnote. Reliable sources include specs, docs, books, well-known reference sites (MDN, Wikipedia, etc.), and high-quality blogs (CSS-Tricks, AListApart, etc.). Unreliable sources include random blogs or portfolio sites, major news media, The Onion & Buzzfeed. Make sure whatever source you use is still current and applicable - tech moves fast and, while some foundational concepts are timeless, most articles will show their age within a year or two. If you're covering material that's likely to evolve, like browser support for emerging features, look for authoritative sources that will grow with us. Remember that footnotes are aimed at students as much as instructors, so try to keep your sources as approachable as possible. Not everything needs to link to the W3C spec!
Our lessons and assignments will be bridged by shared concepts, but shouldn't be dependent on each other. If you find yourself needing to link between multiple lessons, reconsider your approach and try to comparmentalize new information as much as possible. We want to prevent students from getting "content exhaustion" by making each lesson as self-contained experience!
We use the serial comma. Capitalize proper nouns & acronyms ("HTML", "CSS") and, when in doubt, follow the source formatting (ie: "Sass" not "SASS", per the official site). Use Title Case For Section Headings. Provide a language for your code blocks - "pseudocode" or language-agnostic blocks will fail to render appropriately. Make sure to surround images with a blank line in your Markdown so they render as expected. Footnote content should always go at the bottom of the page - not in-between sections or inline.
## Section Heading
### Subsection Heading
Section content with `inline code` sample.[1]
- List item 1
- Don't nest lists
- List item 3
```lang
// Use comments to explain complex code
fenced(Code);
// Make sure to include the language on the opening fence!
```
#### Video Title
###### Short description of video.
!video wistia-url-id
[1]: Here's some [footnote context](http://footnote.url)Lessons on the The Iron Yard's Learn platform are a major representative for our brand and need to be structured in an approachable, visually pleasing way. With this in mind, we've laid out some simple guidelines to follow while writing lesson content.
Lessons are made up of two parts:
-
"Description": a short (3-5 sentence) summary of the lesson. This will show up as forematter on the lesson page and should be a rough outline of what's covered in the lesson.
-
"Body": The lesson content. Parsed like Github-flavored Markdown with some custom elements (detailed below). Try to keep your lessons at 1500 words or less - you won't be truncated if you need to go over, but we'd like to keep our content bite-sized.
Check out this "Your First CSS" lesson for a good example of an ideal layout.
Assignments are how we make our lesson content "stick". An assignment serves as an exercise for the students and an assessment method for the instructors. Assignments are tightly scoped to Units and Lessons via Topics. Like Lessons, Assignments work best when they conform to a predictable structure.
Assignments have more stringent layout requirements than Lessons. There are 6 key parts:
-
"Description": Similar to the same property of Lessons. A short summary of the assignment, including the key topics it covers. This will be the "abstract" on our student-facing side, so keep it short (1-2 sentences) and clear. We shouldn't need Markdown or any media content here.
-
"You Should Know": Prerequisites for completing this assignment. These will eventually be "topic" resources that link Lessons and Assignments, but for now it will just consist of a list of basic concepts the assignment addresses.
-
"Your Mission": The assignment itself. Here, we describe the overall goals of the assignment and general expectations. We should include enough context that a student can complete it with little/no guidance. Generally, introductory content should go beneath the "Your Mission" heading, and objectives should go within one of the three difficulty level subheadings in this section: "Explore", "Adventure", and "Epic" modes (formerly "Normal", "Hard", and "Nightmare", respectively). Assignments aren't required to have all three difficulty levels, but it's strongly recommended.
Objectives should be structured with a "challenge" and a "goal". The challenge should be a declarative statement guiding students to the solution without providing step-by-step instructions. The goal should be a description of the deliverable associated with the preceding challenge. Multiple objectives can be included in any difficulty level. See this example assignment for an idea on how a Mission heading should be structured. -
"Requirements for Completion": A list of all deliverables required from a student for the assignment to be considered "complete". This should be explicit! Be sure to note the format for submissions and any file names you'd like (for automated testing or organization). If a deliverable is keyed to a specific difficulty level, it should be noted in italics after the item. For example: - HTML text file named "index.html" - Audio file named "background-music.mp3" (Epic mode)
-
"You May Need": This is an space to include critical resources for completion. If the assignment requires any pre-fab code or images, they should be included here. We can also use this section to aggregate remote resources, such as API endpoints or service links. "You May Need" is optional: if an assignment doesn't require any extra resources to complete, this section may be omitted.
You can copy this gist as a blank Assignment template.