# Lesson creation guide

As a lesson creator with Oppia, you will be creating content that will be delivered directly to students facing education inequality across the world. Ultimately, everything we do at Oppia is to help you create these effective lessons. This series of wiki pages will help you get started so that you can begin making an impact right away. 

<h2>Anatomy of an Oppia Lesson</h2>

Here is a list of terms that we’ll be using to describe the various parts of lessons:
* <b>Topic</b> - A topic, like Fractions, consists of one or more stories. Sometimes, more than one story may be needed to teach a topic fully.
* <b>Story</b> - A story is a group of explorations, and is the new name we’ll be giving to what are currently called “collections”. Each exploration in the same story follows the same story arc and shares the same setting/characters.
* <b>Exploration</b> - This is a structured learning experience that is part of a story, and provides the learner with an active way to learn new concepts, as well as targeted feedback. It is the core unit of learning in Oppia.
* <b>Skill</b> - This is a concrete learning outcome that describes something that a learner should be able to do. It is usually stated in the form “Given X, compute/calculate/draw/etc. Y.” For example: “Given a fraction, identify its numerator.”
* <b>Concept Explanation</b> - This is a non-story-based explanation of how to perform a particular skill. It serves as a reference/reminder for students who may have encountered the skill before but forgotten how to carry it out.
* <b>Misconceptions</b> - This is a list of misconceptions that students often have about a particular skill. It is used by exploration authors to ensure that questions have a sufficient amount of targeted feedback.
* <b>Question</b> - This is a standalone question that may be used by students as part of a practice session.

<h2>High-Level Process Flow</h2>
This is the high-level process of how a lesson is created. When you complete each step, a senior reviewer on the team will work with you to review and finalize the work. Click on each item below to view the guideline and detail of each process:
<ol>
<li><a href="#Skill">Create the Math Skill Tree</a></li> 
<li><a href="#Story">Develop a Story Outline</a></li>
<li><a href="#Table">Build out the Skill Table - Errors, Remediation, Sample Questions, Development of the topic</a></li>
<li><a href="#Script">Create the Script</a></li>
<li><a href="#Graphics">Graphics and Implementation</a></li>
</ol>

<h3>Key Contacts</h3>
For each lesson you create, you will be assigned a lesson coordinator who is there to help mentor you through the process. If you have any questions, please feel free to reach out to your coordinator or contact the team leads below: 
<ul>
<li>Andrew Muliadi (andrewmuliadi@oppia.org), Lesson Creation Lead</li>
<li>Mark Halpin (markhalpin3@gmail.com), Story Content Advisor/Reviewer</li>
<li>Sean Lip (sean@seanlip.org), Math Content Advisor/Reviewer</li>
</ul>

<h2 id="Skill">Skill Tree</h2>
<p>The most basic unit of an Oppia lesson is the skill. A skill is a concrete learning outcome that describes something that a learner should be able to do. It is usually stated in the form “Given X, compute/calculate/draw/etc. Y.” For example: “Given a fraction, identify its numerator.”
</p>
<p>
In this stage, the creator is advised to breakdown the topic into as many concrete skill as possible. The more skills we can generate for a topic, the easier it is to scaffold the skills and guide students towards a deeper understanding of a topic. Since this will be the backbone of your lesson, it is the most challenging, but important step.
</p>
<b>Scope:</b>
<ul>
<li>It is up to the creator to determine what skills should be in scope for a topic. During the review process, your reviewers may discuss why some skills are omitted or suggest additional skills. Creators are strongly encouraged to contribute to these discussions and rationalize with the review team.</li>
<li>As creators break down the topic, make sure to note any pre-requisite skills that may not be part of the topic scope.</li>
<li>When specifying prerequisites, these should indeed include specific skills from previous lessons in the series (as well as specific skills from outside the series, if needed). We will use these to generate random review questions at the start of each lesson, in order to make sure that the student still has mastery of the skills they need (since just because they've seen it before doesn't mean they have it under their belts).
</li>
</ul>
<b>Format:</b>
<ul>
<li>The creator should arrange the skill in a logical manner - building from simpler skills to more complex ones</li>
<li>The creator should arrange relevant skills into groups called “lessons”</li>
<li>It is fine if the skill tree is in a bulleted list form</li>
<li>You may repeat similar skills in different lessons</li>
</ul>
<b>Inspiration and Tips:</b>
<ul>
<li>Look at how textbooks approach a topic. They sometimes do not break down the topic in the manner that we do, but it is a good starting point.</li>
<li>Think of complex questions that you would like the learners to solve then work backwards to find out what skills are needed to solve those questions.</li>
</ul>
<b>Samples:</b>
<ul>
<li><a href="https://docs.google.com/document/d/1VgMugLebqK-8c0nS80BBuQ4Fw49X0oZpU2krD-y2B0U/edit?usp=sharing">Fractions </a></li> 
<li><a href="https://docs.google.com/document/d/1AJ9l5rL-wPwiePYXhBZwreOz8piQ4Ur-KFj1KPCIPvg/edit?usp=sharing">Place Values (page 1) </a></li> 
</ul>
<h2 id="Story">Story Outline Development</h2>
<p>The story component is what makes Oppia lessons so effective. Stories help learners stay engaged - learners relate to the characters and realize the important role that math can play in their lives.</p> 

<p>Usually, a topic will have one story that spans across different lessons. In this stage, you are drafting the high-level story for each lesson.</p>
<b>Format:</b>
<ul>
<li>A brief overview of the characters, settings, and premise</li> 
<li>1 - 2 paragraph describing what happens in each lesson</li> 
</ul>
<b>Inspiration:</b>
<p>One way to figure out a story idea is to determine a specific and relevant action that best demonstrates the concept being taught, e.g. cutting up a cake to demonstrate fractions. This action can then be extended into a story idea that describes what is happening, story-wise, in each exploration.</p>

<p>If you need help coming up with an idea, speak to your lesson coordinator. He or she will also help you schedule a call with Mark Halpin (markhalpin3@gmail.com) who is the Story Content Advisor/Reviewer.</p>
<b>Tips:</b>
<ul>
<li>Try to empathize with the learner who is taking your lesson - what do you think they’ll care about? Do you think they will be able to relate with your characters?</li>
<li>Use possible mathematical fallacies or misconceptions to your advantage - these are areas where you can add a little bit of peril to your protagonist’s adventure</li>
<li>Learners should have a tangible feeling of satisfaction/accomplishment at the end of each lesson, by virtue of having done/solved something worthwhile.</li>
<li>Keep the setting and premise relatively simple- ultimately, your lesson will be mainly driven by the math, so we want just enough story to keep the students engaged.</li>
</ul> 
<b>Samples:</b>
<ul>
<li><a href="https://docs.google.com/document/d/1EWUXEOqk490T6SRR4kbOFL4se3Vzq9ou5PLqE6TN_w8/edit?usp=sharing">Fractions</a></li>
<li><a href="https://docs.google.com/document/d/1AJ9l5rL-wPwiePYXhBZwreOz8piQ4Ur-KFj1KPCIPvg/edit?usp=sharing">Place values (Storyline section)</a></li>
</ul>
<h2 id="Table">Skill Table</h2>
<p>Developing the Skill Table is the stage that will help you organize and further elaborate the math skills you have prepared in the previous steps.</p>
<b>Format:</b>
<ul>
<li>Table Format that consists of the following columns:<ul>
<li>Skill - these are the same skills that were listed in the Skill Tree. The skills are listed in the order that they would be presented in the actual lesson.</li>
<li>Specific Errors - This column lists out the common mistakes or misconceptions learners make when dealing with specific skills.</li>
<li>Remediation - This column lists out how the lesson would help learners address the misconceptions</li>
<li>Development of the Topic - this is the precursor to your script and is the most important column. It outlines how you plan to explain various skills and the questions that will accompany the explanation. These questions will appear in the script. Some special notations in this column include: 
<ul>
<li>denote questions that introduce new concepts with a "[concept]" tag</li>
<li>denote questions that reinforce previous concepts in the lesson with a "[test]" tag</li>
<li>denote questions that reinforce previous concepts in past lessons with a "[recap]" tag. Begin each lesson (except the first one) with recap questions</li>
<li>end each lesson with a series of questions that test skills within the lessons and denote them with a "[Final Challenge]" tag. Unlike the "[test]" tag, [Final Challenges] are always at the end of the lesson</li>
<li>color code all types of questions with Green, Yellow, and Red highlight depending on difficulty</li>
</ul>
</li>
<li>Additional Recap Questions - include additional recap and test questions in this column. We will add these questions to the question bank which will allow us to randomly populate equivalent questions for students; varying the learning experience each time the students take the lesson. Use the same denotation as the ones described in the Development of the topic column.</li>
</ul>
<li>When listing misconceptions, the misconceptions should be specific things, not just "student can't do skill X correctly". I.e., the description should be such that, if you give someone else the question and the description of the misconception, they should be able to accurately predict the student's answer.</li>
<li>Ensure that the questions are staged. One way to verify concretely that you're making leaps that aren't too big is to define for yourself what *single* new skill each new question introduces. Don't introduce more than one skill at a time with each question. Be careful to also account for "hidden" skills that aren't taught explicitly in the lessons you're creating, such as "parsing a complicated word problem" or "knowing the relationship between distance, speed and time".</li>
<li>List Prerequisite skills, acquired skills and practiced skills before the table of each lesson (see sample).</li>
</ul>
<b>Tips:</b>
<ul>
<li>Start with a target question in mind and work backwards to determine what skills the students need and where the pitfalls are. Work the problem step-by-step. It is likely that those intermediate steps reflect critical skills.</li>
<li>When writing the math breakdown, don't worry at all about Oppia's current technical capabilities. Assume that Oppia can do anything you want it to, and ask any question type you want it to. That allows the math breakdown to be used as an "ideal" reference and could drive future improvements in Oppia's tooling.</li>
</ul>
<b>Samples:</b>
<ul>
<li><a href="https://docs.google.com/document/d/1GNP_slUbT1ZjA9BhDquvSTEWEIBlBgM2NdXcaCDSeVo/edit">Fractions (See the tables)</a></li>
</ul>

<h2 id="Script">Script Writing</h2>
<p>The Script Writing is the stage that combines the work you did in the Skill Table with your Story Outline.</p> 

<p>In the stage, you are drafting what the final product of your lesson would look like on the Oppia site. This means that you will specify the exact dialogue, graphic requirements, card interaction, and question type for your topic.The flow of your script should close follow the “Development of the topic” column in the Skill Table.</p>

<b>Format:</b>
<ul>
<li>Named cards that specify the exact dialogue, graphic requirements, card interaction, and question type.</li>
<li>Please see the full style guide in Section 3 of this document (we probably need to pull this out to a new doc): <a href="https://docs.google.com/document/d/19_zpqlqM9DrA7E9hSLDiXFqk3RhZ0AHsfVlPivEM5a4/edit#">Click here</a></li>
</ul>

<b>Tips</b>
<ul>
<li>Do follow the style guide carefully - it will help our graphic designers and it will help you implement the lessons.</li>
<li>Don’t get too carried away by the dialogue - keep it engaging, concise, and close to the math content</li>
<li>Make sure your writing style can be easily understood by the target audience. Humor is good, but universal humor as opposed to puns or word play is even better.</li>
</ul>
<b>Samples</b>
<ul>
<li><a href="https://docs.google.com/document/d/1NbVO8Dv9V81eNGGjIOVakDD02E6uFX-Sp4NuLkCJaWU/edit">Ratio lesson 1</a></li>
</ul>

<h2 id="Graphics">Graphics And Implementation</h2>
<p>The Implementation Stage is where you take the details you wrote out in the script phase and put it into the Oppia platform. The migration of the script to the platform will be verbatim. Additionally, you will be paired with a graphics designer who will help create the graphics in your script.</p>
<b>Format</b>
<ul>
<li>Oppia Platform</li>
</ul>
<b>Notes</b>
<ul>
<li>The alt text for images should clearly describe the images for users who can't see them. E.g. instead of "James", write "A picture of James, jumping excitedly, in a yellow sweatshirt." </li>
<li>Crop images so that the image is a tight fit with zero empty space around the borders.</li>
</ul>