Oppia User Guide

Oppia is an open source learning platform with the goal of providing engaging content to learners. Anyone can create and share interactive lessons (explorations) with the aim of recreating a one-on-one tutoring scenario.

This interactivity is what makes Oppia unique. Many of the educational tools on the Internet provide a unidirectional flow of information which makes it hard to create engaging, feedback-rich experiences for learners. However, Oppia comes with several built-in interactions and responses that make it possible to personalize feedback to a learner’s answer. Over time, explorations can be improved as more learners engage with the content.

Oppia’s mission is to provide high-quality, accessible learning experiences to everyone around the world.

To begin, we suggest getting familiar with the key terms used in Oppia first.

Lesson Creators - start here

Learn how to create engaging explorations, including how to write a good introduction, and plan your exploration.

Contributors to Oppia

Looking to contribute and add value to Oppia’s lessons? Learn how you can translate a lesson or record a voiceover among other things, and help make lessons even more accessible!

Admins and Topic Managers of Oppia

Learn the steps involved in planning a lesson, as well as how to create a topic and skill in Oppia.

Reviewers of Oppia

Learn the procedure to review translations, voiceovers and questions in Oppia.

Key Terms used in Oppia

Terms

• Topic

• Story

• Skill

• Subtopic

• Exploration

• Card

• Content

• Interaction

Topic: A topic refers to the subject matter to be taught (e.g., Decimals, Fractions). A topic will consist of a set of stories.

Story: Stories are non-contrived (realistic) scenarios that teach the topic. If the topic is Decimals, then the first story—aiming to introduce the concept—might be a scenario where a customer is in a shop and has to pay an amount in dollars and cents. A story consists of a linearly ordered set of explorations or lessons, i.e., within a story, a student must complete the first lesson before moving on to the second.

Skill: A skill is simply what the student should be able to do. Following our example of Decimals, skills might include ‘Comparing Decimals’, ‘Adding Decimals’, ‘Converting Decimals to Fractions’ etc. Skills are normally associated with a topic.

This diagram summarizes the relationship between the above concepts:

Topic hierarchy in Oppia

Subtopic: In Oppia, a subtopic refers to a group of skills within a topic. Subtopics are created to provide students the opportunity to review and practice skills.

Note

• If a skill is not assigned to a subtopic, students will not be able to practice that skill.

• If a topic contains no subtopics, students will not be able to practice the topic.

Subtopics created for practicing skills

Exploration: Explorations are lessons or learning units in Oppia. From a learner’s perspective, explorations resemble a conversation between themselves and the tutor. This conversation takes the shape of:

• the tutor asking questions (content)

• the student answering (interaction)

• the student getting feedback (response)

Card: An exploration is made up of a series of cards, with each card comprised of the tutor’s question (the content) and the student’s answer (the interaction).

Content: Content refers to the question the tutor asks in a card. The content may include pictures, and a brief description of the context before a question is asked.

Interaction: Interactions refer to the answer that the student gives to the content (question asked), and the resulting response (feedback) from the tutor. The type of interaction depends on the type of exploration—a Math exploration has different interaction options from a Programming one.

This diagram summarizes the relationship between the above concepts:

Exploration hierarchy in Oppia

Creating a new lesson

In this section, you will learn how to:

• Create a new exploration

• Write the introduction

• Create content (questions)

• Add interactions (answers)

• Add responses (feedback)

• Add hints to a question

Watch this video to learn how to create an exploration, or if you prefer reading the instructions instead, keep scrolling down.

Create a new exploration

1. To create a new exploration, from the Creator dashboard, click the Create button in the top right corner.

Fig. 1

2. You will see the Exploration Editor page. Now you will have to:

• give your exploration a title

• write the introduction

Fig. 2

3. To create a title for your exploration, click ‘Untitled Exploration’ in the top left corner. This will take you to the Settings page. In the first field Title, type in a descriptive title for your exploration. We’ll look at the other fields on this page in another section.

4. To get back to the Exploration editor page, click the Editor button.

Fig. 3

Write the introduction

What to think about

Your goal here is to engage or hook the learner to continue on with the exploration. Write as if you are having a conversation with the student. Introduce your topic, the protagonist of your story, or set the scene.

You might also want to include what the student will already need to know beforehand and what they will need for this exploration (e.g., a paper and pen).

1. To begin writing the introduction, click inside the white box and begin typing. You will see different formatting options available to you.

Fig. 4

2. When you’re done writing the Introduction card, click the button, then click the button.

3. A pop-up box will appear for you to choose an interaction. If you haven’t yet asked a question to your reader in the Introduction card, you can select ‘Continue Button’. Interactions will be covered in more detail in the Add Interactions section.

Fig. 5

4. Edit the Button label if you wish and then click the button.

5. You will now see the ‘Continue’ button below the Introduction card. Click on the bar below Learner’s Answers and Oppia’s Responses to direct what happens when the button is clicked.

6. To create a new card, click on the drop-down menu below Oppia directs the learner to… and select ‘A New Card Called…’. Enter the name of the new card in the blank field and click on the button.

Fig. 6

7. The new card is now visible in the top-right section of the screen under Exploration Overview. Click on the card here to begin creating content.

Fig. 7

Create Content

What to think about

It helps to have a specific question in mind that you want the learner to be able to answer at the end of the exploration. An example would be “What is the decimal equivalent of 1/2?” From here, come up with a series of questions and answers that will help the learner understand the concept of comparing fractions to decimals. This series of questions will form the main path of your exploration.

Now, think about how you want to present your exploration. Do you want it in the form of a story? Try to characterize your cards as much as possible—is an authority figure asking the question? Is the learner helping a character out by answering? Students are much more likely to remain engaged in this way as opposed to a rote question-answer card.

When creating the exploration, focus on simplicity and create something linear (you can always add complexity later). Remember your goal with creating cards is to model a conversation between yourself and the student.

There are four parts to a card:

1. Content

2. Interaction

3. Response

4. Hint

In this section, we’ll focus on the content where you will ask a question to the learner.

1. In the new card just created, click inside the white box to begin typing the content. The goal is to ask a question, so you may set the scene and then pose the question. When you’re done, click the green button.

Formatting Content

The editor box gives you several formatting options including bolding, italicizing, inserting images, links, videos etc. As an example, you may choose to add an additional tab in this section to provide extra information using the ‘Insert tabs’ button (if you want to provide a hint but not have it show up right away, see the Add Hints section instead). This will end up looking like this:

Fig. 8

Add Interactions

What to think about

How do you want your learner to answer the question? Do you want them to type in an answer, or choose items from a selected list? Perhaps you want the learner to drag and drop items in a particular order. Oppia has several built-in interactions sorted by subject matter that you can choose from.

Now that you’ve posed a question, the next step is to add an interaction—the type of answer the learner might give.

1. Click the button.

2. The Choose Interaction pop-up box appears. Click on the desired interaction which will bring up the Customize Interaction box. The customization options will depend on the type of interaction chosen. In the example below, we have selected the Multiple Choice interaction.

3. When you have finished customizing the Interaction, click on the button.

Fig. 9

Add Responses

What to think about

The Response section is where you decide how Oppia should respond based on the learner’s answer. Do you want the learner to redo the question or move them to a different card? If you want them to try again, include some constructive feedback about why the answer was wrong. Even if they have answered correctly, explain why the answer was right.

1. After you save an interaction, the Add Response pop-up box appears.

2. Choose the learner’s possible answer, and add the appropriate response. To add a new response, click the button. You can direct the learner to a new card based on a certain answer by creating one here.

Fig. 10

3. When you have finished adding responses, click the button. This brings you back to the Editing screen where you can view the responses you’ve created. From here, you can add a new response, or edit or delete the responses you’ve created by clicking on the relevant box.

4. You will notice a checkbox titled Solicit Answer Details when you come back to the Editing screen. If you would like Oppia to ask the learner to explain why they chose the answer on that card, checkmark this box. You can find more details on this in the Improvements tab page.

Fig. 11

A word on Loopbacks

When a learner answers incorrectly, there is an option to get the learner to ‘try again’ or loop back and answer the question again. It isn’t always a good idea to do this. Think about whether you are able to group the possible ‘wrong’ answers in such a way that you can provide detailed feedback to the learner.

If you cannot do this, i.e., if the possible ‘wrong’ answers have come in through a text-field (so you have no way of knowing what the learner might type), or if there are lots of wrong answers to a question—it is better to send the learner to a separate branch to address their misconceptions. Looping them back to the question in this case might cause frustration as they will end up trying to guess what you want them to say.

Add Hints

When a Hint will appear

To prevent learners from abusing the Hint feature, a hint can be requested only if one of the following conditions is satisfied:

• The learner submitted a wrong answer at least once.

• It has been more than 30 seconds since the learner last submitted an answer.

You may add one or more hints to a card in case the learner gets stuck.

1. To add a hint to a card, click the button at the bottom of the Editing screen.

2. The Add Hint pop-up box appears. Type in the hint and click the button.

Fig. 11

Editing and Publishing a lesson

In this section, you will learn how to:

• Edit content

• Work with older versions of your exploration

• Review errors and end your exploration

• Preview the exploration

• Save and publish the exploration

Watch this video to learn how to edit and publish an exploration, or if you prefer reading the instructions instead, keep scrolling down.

Editing content

1. In your exploration, you can navigate to different cards at any time by clicking on the card in the Exploration Overview section.

2. From here, you can make changes to any section within the card. To delete an entire card from the exploration, click on the small x in the top-right corner of the card.

Fig. 1

3. To delete the entire exploration, go to the Settings button in the navigation bar, and click the button located at the bottom of the page.

Working with older versions of the exploration

1. Every time you save your exploration, Oppia keeps a record of that version. To save a draft of your exploration, click the button in the top navigation bar. In the pop-up box that appears, you can type in an optional message describing the changes made.

Fig. 2

2. You can view a list of all saved versions at any time by clicking the History button.

Fig. 3

From the History screen, you have the following options:

Compare selected revisions

Select any two previous versions and click the button to view what was changed.

Fig. 4

Revert to a previously saved version

Click the Revert link next to any version of your exploration to revert and go back to using that version. This change will now be recorded and added to your History under the list of changes.

Warning

When you revert to an older version, you will lose any unsaved changes in your exploration. If you think you might want to come back to your current version at some point later on, make sure you save your draft before reverting so that Oppia has a record of it.

Download a version

Click the Download link next to a version to download a zip file that will contain all the data for your exploration. It will include a YAML file as well as any additional asset files (such as images) that are part of your exploration. You can now share this file with other people if you wish.

Fig. 5

Reviewing errors and ending the exploration

1. In the Exploration Overview section, you might see yellow warning signs next to the card(s). You need to resolve these warnings before you can publish your exploration. Hover your mouse over these signs to read the warning messages, then click on the card to resolve the issue.

Fig. 6

2. Another common warning message tells you that you haven’t properly ended your exploration. To do this, go to the last card of your exploration and click on the button. In the pop-up box, click the End Exploration interaction button.

Fig. 7

3. In the Customize Interaction (End Exploration) box, you can recommend additional explorations to the learner by clicking on the Add exploration ID button. Otherwise click the button to end the exploration.

Fig. 8

Finding the ID of a published exploration

To find the ID of an exploration, go to it and click on the Settings button in the navigation bar. Look under the title Permissions to find the exploration URL. The ID is the last string of characters that appears after ‘/explore/’.

Fig. 9

Previewing the exploration

1. To preview your exploration from the beginning, go to the first card in your exploration and click on the Preview button in the navigation bar. This shows you what it would look like to a learner.

Fig. 10

2. If you want to make changes at any time during the preview, click the Editor button to return back to editing mode.

Saving and publishing

1. Save all changes in your exploration before publishing by clicking the button.

2. To publish the exploration, click the button.

3. You will be asked to fill out additional details for your exploration such as a goal, a category, tags etc. Click on when done.

4. Finally, click the button.

5. Once published, Oppia will display the URL for your exploration which will now be available in the Oppia library for anyone to learn. Congratulations!

Fig. 11

Improving a lesson

In this section, you will learn how to make your exploration better by:

• Using the Improvements tab

  • Getting feedback

  • Suggestions for improvement

  • Answer details for a card

  • Exiting early

  • Multiple incorrect answers

  • Getting stuck in a loop

• Adding branches to an exploration

Watch this video to learn how to improve your exploration, or if you prefer reading the instructions instead, keep scrolling down.

Using the Improvements tab

Oppia’s explorations are designed to be improved over time as learners engage with the content. You can use the Improvements tab to determine how learners are using your exploration and what they think about it, and make changes accordingly.

1. Click the Improvements button in the navigation menu.

2. At the very top of the page, you can see how many Open Tasks are waiting for your review.

Note

By default, only open tasks are shown in the Improvements screen. If you want to see tasks that have been previously resolved, uncheck the Show only “Open” tasks box. This will show you any feedback or suggestions that you previously received on the exploration. All other tasks—once resolved—are permanently deleted.

Fig. 1

The following are the types of open tasks you might see.

Feedback on a card

Learners have the option to provide feedback on each card as they play through an exploration, as well as at the end when they are asked to review the exploration. If they have provided any feedback, you will see a task similar to the image below.

Fig. 2

1. To change the status of the feedback or write a message in response to the feedback for your record, click on the button.

2. Click when done.

Caution

Leave the status at Open if you are still working on the task. Only use the other options if you want to hide the task from the Improvements screen.

Fig. 3

Suggestions for a card

Learners also have the option to suggest an edit on one or more cards, e.g., a change in the content, formatting etc. This comes through as a Suggestion task in the Improvements screen.

Fig. 4

1. Click the button and then the button to take action on this suggestion.

2. After reviewing the changes suggested by the learner, you can either accept or reject the suggestion.

Fig. 5

3. Enter a new message if you wish to add to the message thread and change the status of the suggestion as required. Finally, click the button.

Fig. 6

Answer details for a card

If you checkmarked the Solicit Answer Details box while creating your exploration, Oppia will occasionally ask a learner to explain why they chose a certain answer for that card.

Fig. 7

Whenever a learner explains why they chose their answer for a card, you will see the details in the Improvements screen as shown below.

Fig. 8

1. To review the details, click the button and click under Answer details to expand the comment.

Fig. 9

2. To delete any Answer details received, checkmark the Select box next to each of them and click on the box.

An example on improving an exploration

Let’s say you asked the question: Which is greater: 0.834 or 0.2? and requested an explanation from the learner for their answer. The learner selected the right answer, but explained they chose it because it was a longer number. This is obviously a misconception, so you may then decide to include additional cards beforehand or branch out to focus on place value or the decimal-fraction link.

Exiting a lesson early

Another issue you might see here is when a learner quits your exploration early without completing it to the end.

Fig. 10

Oppia will provide one or more sample playthroughs that will outline exactly how the learner proceeded through the exploration from start to finish.

1. To see exactly what the learner did, click on the green View Playthrough button.

Fig. 11

2. To permanently remove the task from the Improvements tab, click the button.

Tip

Look out for patterns here—if learners seem to quit at one card in particular, then perhaps the difficulty level is too high, or the content is ambiguous.

Answering incorrectly multiple times

Oppia can also flag when a learner submits an incorrect answer several times on a card.

Fig. 12

1. To see exactly what the learner did, click on the green View Playthrough button.

2. To permanently remove the task from the Improvements tab, click the button.

Tip

If it makes sense, consider adding an incorrect answer in the Learner’s Answers and Oppia’s Responses section of the card. This will let you provide explicit feedback and may work particularly well with open-ended questions or cards with a ‘Text Input’ interaction.

Fig. 13

Revisiting the same card multiple times

If a card in your exploration loops back to an earlier card in case of an incorrect answer, a situation may arise where a learner keeps returning to the earlier card and gets stuck in a cyclic loop. This will appear in the Improvements screen as shown:

Fig. 14

1. To see exactly what the learner did, click on the green View Playthrough button.

Fig. 15

2. To permanently remove the task from the Improvements tab, click the button.

Tip

If a learner keeps returning back to an earlier card, it appears they have not grasped the concept in that card. Consider rewriting the card to explain the concept more clearly, or provide more explicit feedback when they answer incorrectly.

Adding branches to an exploration

When you first create an exploration, it’s easiest to begin by creating a single series of questions and answers that might help a student understand the concept. This is the main ‘trunk’ of your lesson. You can start to add branches to this trunk as learners engage with your lesson and you notice certain patterns in the way they answer.

For example, if many students are consistently getting the incorrect answer on one card in particular, you could redirect those students to a more elaborate explanation by sending them to a different branch (with one or more cards) which would eventually rejoin the main path of your exploration.

Adding a branch to an exploration

Let’s look at an example where the learner is asked to compare decimal place values.

Fig. 16

If you notice quite a few students have been answering ‘Hundredths’ to this question, this is an indication that they are mistakenly equating place values for decimals with place values for whole numbers. To correct this misconception, you can branch out from this card and provide further explanation.

1. In Editor mode, go to the card in question and under Learner’s Answers and Oppia’s Responses click on the incorrect answer option (Hundredths).

2. To branch out from this incorrect answer, click on the drop-down menu and select A New Card Called… Give the card a title and click on .

Fig. 17

3. The new card is now visible in the Exploration Overview section. Click on this card to add content.

Fig. 18

You may choose to add several cards on this branch and then finally redirect the learner back to a card on the main path of the exploration.

Fig. 19

Customizing lesson settings

In this section, you will learn how to customize your exploration settings with:

• Basic Settings

• Advanced Features

• Changing email preferences

• Deleting an exploration

Watch this video to learn how to customize your exploration, or if you prefer reading the instructions instead, keep scrolling down.

Basic Settings

Before publishing an exploration, you will be required to fill out certain fields in the Settings page.

1. To access the Settings page, click the Settings button in the navigation bar.

2. Fill out the fields under Basic Settings.

Fig. 1

3. To see a preview of your exploration and how it would appear to a learner as they search in the library, click on the Preview Summary button. The Title and Goal fields are displayed in the preview.

Fig. 2

Advanced Features

Automatic Text-to-speech

This setting is available under Advanced Features. The Automatic Text-to-speech feature is enabled by default and automatically generates audio from the text in your cards.

When the feature is enabled, learners will see an Audio button as they play through the exploration, which will generate a computerized reading of your card. If you disable the feature, the button is not visible to learners.

Fig. 3

Tip

Disable the text-to-speech feature if your exploration content consists of multiple languages.

Correctness Feedback

The Correctness Feedback feature lets students know when they have selected a right answer by displaying a short animation that looks like this:

Fig. 4

1. To enable this feature, click on , go to Advanced Features and click the button next to Correctness Feedback so that it is ‘On’.

2. In the Editing screen, you will now see an option to identify an answer group as correct in the Learner’s Answers and Oppia’s Responses section. Checkmark the box within the correct answer group. You can add several possible answers to a group if there is more than one correct answer.

Fig. 5

3. Save your changes. Now the learner will be able to view the ‘Correct’ animation if they input an answer you have identified as ‘correct’.

Changing Email Preferences

The default setting in Oppia is for an exploration creator to receive notifications whenever a learner submits feedback or suggestions for your exploration.

You can stop these notifications by clicking the Mute button under Feedback/Suggestion Email Preferences.

Fig. 6

Delete an Exploration

Finally, you can delete your exploration if you wish by clicking the button at the bottom of the Settings page.

Contributing to a lesson

Thank you for your interest in improving Oppia’s lessons with your contributions! This section will cover how you can contribute:

• Translations for lessons

• Questions for reviewing skills

• Voiceovers for lessons

Translating lessons

Translations help even more learners access Oppia’s lessons, while also giving you a chance to use your language skills to help create opportunity around the world. When you submit translations, they are sent for review. You can view the status of all your translations in the My Contribution page.

Watch the video to learn how to contribute translations, or if you prefer reading the instructions instead, keep scrolling down.

1. From the Community Dashboard, go to the Translate Text menu header.

2. Select the language you want to translate into from the drop-down menu under Translate Text in:.

3. You will see a list of chapters that has not yet been translated into the language selected.

Fig. 1

4. To begin translating, click the Translate button next to a chapter. A pop-up window appears with the content to be translated shown on top. Type in the translations in the text box at the bottom.

Fig. 2

Using the Copy Tool

To copy over non-text items like images, click the Copy Tool button On. The content to be translated is now split into different outlined sections, and the mouse icon shows a green plus sign as shown in the image above.

• Click on the section you want to copy over. For example, to copy an image, click the image.

• The Customize This Component window opens. Translate any text in this window if needed. Click Done to return back to the translation card.

Fig. 3

• The item is now copied over in the translated section.

Fig. 4

5. To move on to the next card and save the current card’s translation, click .

6. To move on to the next card without translating the current card, click skip.

7. To exit, click Cancel. Translations done on previous cards are already saved.

8. To view your translations, go to the My Contribution page where you can also see its status.

Fig. 5

Guiding Principles

To ensure your translations have the best chance of being accepted during review, keep these principles in mind:

• Preserve the voice and meaning of the original text. This doesn’t mean you have to translate literally, rather you are aiming for natural language that stays close to the source. A good tip for natural-sounding translations is to imagine explaining the sentence verbally to someone—and render that to written form.

• Ensure that all of the meaning in the original text is present in the translation.

• Stay consistent with translation choices.

Before you submit your translations, ask yourself:

• Have I added or subtracted information anywhere?

• Are there terms that I am unfamiliar with? If so, have I researched the term and consulted online resources?

• Have I been consistent with my translation choices across the lesson?

• Have I proof-read and reviewed my translations before submitting?

Note: When translating something, if you see broken images, do not submit it. Please try to gather logs from the dev console and share it with us.

Text Corpora Resources

Linguee Tradooit (French, Spanish and English)

Contributing practice questions

As a contributor, you are suggesting questions for skills learned by the student. These questions form part of the review material that learners will use to practice that specific skill.

Watch the video to learn how to contribute questions, or if you prefer reading the instructions instead, keep scrolling down.

1. From the Community Dashboard, go to the Submit Question menu header. Here you will see a list of skills (and their Topics) to which you can start contributing questions.

2. Click on Suggest Question next to a skill.

Fig. 1

3. Select the difficulty level of the question you want to create. If the skill creator has created rubrics for each difficulty level, you will see them here.

Fig. 2

4. Click Done and you will be taken to the Question Editor.

The Question Editor is comprised of the following sections:

• Create Question

• Add Interactions

• Add Responses

• Add Hint

5. To begin creating a question, click within the box and type the question in. Write the question as if you are having a conversation with the student. Click when done.

Fig. 3

Add Interactions

Now that you’ve posed a question, the next step is to add an interaction—the type of answer the learner might give.

Interactions

How do you want your learner to answer the question? Do you want them to type in an answer, or choose items from a selected list? Oppia has several built-in interactions including fraction or number inputs that you can choose from.

6. To add an interaction, click and select the desired interaction which will bring up the Customize Interaction box. The customization options will depend on the type of interaction chosen. In the example below, we have selected the Multiple Choice interaction.

7. When you have finished customizing the Interaction, click on the button.

Fig. 4

Add Responses

The next step is to add responses.

Responses

The Response section is where you decide how Oppia should respond based on the learner’s answer. Include some constructive feedback about why an answer was wrong. Even if they have answered correctly, explain why the answer was right.

8. After you save an interaction, the Add Response pop-up box appears.

9. Choose the learner’s possible answer, and add the appropriate response or feedback. To add a new response, click the button.

10. At least one of the answer groups must be marked as correct as shown in the image below.

Fig. 5

11. When you have finished adding responses, click the button. This brings you back to the Editing screen where you can view the responses you’ve created. From here, you can add a new response, or edit or delete the responses you’ve created by clicking on the relevant box.

12. You will notice a checkbox titled Solicit Answer Details when you come back to the Editing screen. If you would like Oppia to ask the learner to explain why they chose the answer on that card, checkmark this box. You can find more details on this in the Improvements tab page.

Fig. 6

Add Hints

The final step is to add a Hint.

13. To add a hint to the question card, click the button at the bottom of the Editing screen.

14. The Add Hint pop-up box appears. Type in the hint and click the button.

15. You have now completed all sections of the Question Editor. Click Done to close the editor.

This sends your question for review. To check the status of your contributions, you can go to the My Contribution page and see the status under the Questions category.

Fig. 7

Adding voiceovers to lessons

Voiceovers help make Oppia’s lessons more accessible to non-native speakers. In addition, they give a touch of personality and introduce another dimension to a lesson.

In this section, you will learn how to:

• Apply to become a voiceover artist

• Record voiceovers for a lesson

Don’t forget to check out these guidelines for recording a good voiceover.

Watch the video to learn how to contribute voiceovers, or if you prefer reading the instructions instead, keep scrolling down.

Applying to become a voiceover artist

If you want to contribute voiceovers to lessons, you will first need to apply to become a voiceover artist. You can do so by submitting a recording from an exploration card for review. If your recording is approved and accepted, you will be able to record voiceovers in Oppia.

1. Click on the menu header Voiceover in the Community Dashboard.

Fig. 1

2. Select the language from the drop-down menu. You will see the chapters available for contributing voiceovers in that language.

3. To submit a voiceover application, click the button.

4. You will see the first card of the exploration. Use any audio recording software of your choice to record a voiceover of this card’s content.

Fig. 2

5. To upload the audio file, click Choose File, select your file and click .

Note

Currently Oppia only supports the MP3 file format for the audio file.

6. Your application has now been sent for review. You will not be able to submit any more voiceovers for this or any other lesson until your application is accepted.

7. To check the status of the application, go to the My Contribution page, and click on Voiceover Applications. Once your application has been accepted, you will have to acknowledge the acceptance by clicking the Acknowledge button.

Fig. 3

Congratulations! You have been accepted as a voiceover artist in Oppia and can now proceed with recording voiceovers for lessons.

Recording voiceovers

1. To claim an opportunity and begin recording voiceovers, click on the the menu header Voiceover and then click the Claim button next to the chapter. You will be taken to the Voiceover screen of the exploration editor.

Fig. 4

2. You may choose to record the voiceover directly on the Oppia platform or upload a separate audio file. To record on Oppia, click the Record button, or press R on your keyboard and begin speaking. To upload a file, click the Upload button.

3. When you have finished recording, press or press R on your keyboard again. The following options are now available to you:

• : Playback your recording.

• : Do another retake of the recording.

• : Confirm and finalize your recording.

4. If the card also has feedback, hints and solutions, you will see these tabs activated below the card title. Click on a tab to record the content for that section.

5. To delete a confirmed recording on a card, click .

When you have finished recording voiceovers for a card, you will notice the card is now a different colour in the Exploration Overview. The progress status bar also changes and indicates how many cards are left.

6. Finally, click to save all changes. You can always return back to the Voiceover screen from the Contributor Dashboard and continue recording voiceovers for this chapter. You won’t be able to submit voiceovers for any other chapter until the currently assigned one is completed.

7. Your completed, recorded voiceover will be reviewed by an Oppia reviewer.

Important

If the lesson creator has edited the content of an exploration after you have recorded a voiceover, you will need to record new audio to reflect these changes. Cards that need updating will have an error flag in the Voiceover screen:

Fig. 5

• Click on the card and the specific tab (marked with ) that needs an updated recording. You will see this button that informs you the audio needs to be updated.

• Delete the current recording by pressing and re-record the content.

Guiding Principles

Your interpretation and delivery of the words is the most important factor in recording a voiceover.

• Overall, keep your pace slow as the audience for these lessons might not be familiar with the language. With this in mind, don’t stick to the same pace throughout the lesson. Vary the speed if the content allows for it to keep the lessons interesting.

• Engage with the story as you read!

• If you’re reading highly visual content that requires imagination, then remember to take your time to allow the learner to create their own pictures in their head. For example, ‘The sound of a glass shattering woke her up. She lay in bed, her heart thudding.’ As you read this type of content, try to see the visuals yourself as you read at a leisurely pace.

• Read while understanding the author’s intention. Being a conscious reader will make you a better narrator.

• Remember you are reading for one. Keep the volume of your voice low—no one likes to be yelled at! However, low volume does not mean low energy.

• Don’t fake it. If you’re a male narrating a female character, then don’t try to sound like a female and vice-versa. Instead, think of an ‘attitude’ or trait for the character, e.g., meek, devious or irritable. Pick one trait for each character (of course, this can evolve throughout the lesson) and stick with that to help the listener differentiate between characters.

Guide to planning a lesson

This section will discuss an approach to creating engaging and effective lessons in Oppia. Whether students come to Oppia to reinforce what they learn in school, fill the gaps in their understanding, or learn something completely new—the goal for lesson creators is to consistently provide high quality lessons. Everything done within Oppia is with this goal in mind.

Before reading on, make sure you are familiar with the key terms used in Oppia and the relationship between them.

From a high-level perspective, the process of lesson creation looks like this:

Lesson Creation Process

This page will elaborate on some of the steps in this process namely:

• Creating a Skill Tree

• Creating Questions for Skills

• Developing a Story Outline

• Developing a Chapter Outline

Information on the remaining steps can be found in the contents section.

Creating a Skill Tree

A Skill Tree essentially means identifying and describing the skills that you want the learner to master within the topic. This is the starting point for creating any lesson and is a challenging, but important step. A good way to approach this might be to look at a list of relevant questions and work backwards to identify the skills needed to answer those questions.

Parts of a Skill Tree

The following information is required to create skills:

1. Skill Description: Skill descriptions should:

• Be atomic, concrete and specific.

• Describe an observable behaviour.

• Generally use the format “Given X, compute/calculate etc. Y.” For example, “Given a decimal number, state the place value of each digit.”

2. Review Material: In this section, you will give a broader explanation of the skill to help the learner understand the skill concept. This information as well as the next section ‘Worked Examples’ will be shown to the learner if they have trouble answering questions related to the skill.

Example

If the skill is ‘Identify the whole and fractional parts of a decimal’, then the review material might contain information like ‘The numbers to the left of the point represent the whole number that is greater than 0, the numbers to the right represent the fractional part of the number.’

The above two sections are mandatory to publishing a skill in Oppia. However, the following fields should be filled out as well to enhance the learning experience.

3. Worked Examples: Provide a list of examples that show the learner how the skill can be used to solve questions. You will be able to add images, videos, links etc. when you create this in Oppia.

4. Misconceptions: List common mistakes and misconceptions that a learner would have when dealing with the skills. The description of misconceptions should be really specific, such that anyone should be able to read the misconception and predict how a student will answer given a question. In other words, it is insufficient to just say, “Student cannot do skill X correctly.”

In addition, write down feedback for each misconception you identify that will be shown in the answer group for the question linked to this skill. This information will help question creators ensure that they address misconceptions and provide detailed feedback when creating questions and answer groups for the skill.

5. Rubrics: Rubrics are useful for question creators so they have a guideline when creating questions. Rubrics can be identified for three levels of difficulty—Easy, Medium and Hard.

Example

For the skill ‘Identify the whole and fractional parts of a decimal’, a rubric for an ‘Easy’ question might be: Given a decimal number, identify the whole number and and fractional parts of the number.

A rubric for a ‘Hard’ question for this skill might be: Given a decimal number less than 1, identify the whole number and fractional parts of the number.

Guidelines to creating a Skill Tree

1. More is better. The creator should break down a topic into as many concrete skills as possible.

Example

If the topic is Decimals, then generate all possible skills related to this topic, e.g.,

• Given a decimal with a zero in the one’s place, recognize that the decimal is less than one.

• Given a decimal number, identify the whole number and fractional parts of the decimal.

• Given a whole number, write the decimal equivalent, and so on.

The more skills you can generate, the easier it will be to scaffold the skills and guide students towards a deeper understanding of a topic. During the review process, you will work with your reviewer to determine what skills should be included or excluded within the topic. Be aware of potential ‘hidden’ skills that aren’t taught explicitly in the lessons.

2. Think logically. Arrange the skills in such an order that they build upon one another, i.e. a learner should be able to acquire a skill without a prerequisite knowledge of skills that come after it. This will make it easier to plan the lesson structure in the next step. As students progress through lessons, they will be able to build upon knowledge and skills previously acquired.

3. Group skills into subtopics. Once you have a list of skills arranged in a logical manner as described above, group the skills into subtopics. This gives students the opportunity to review and practice skills.

Example

Subtopic: Introduction to Decimals

• Given a decimal with a zero in the one’s place, recognize that the decimal is less than one.

• Given a decimal number, identify the whole number and fractional parts of the decimal.

Subtopic: Decimal concepts

• Given a decimal number, state the place value of each digit.

• Given a decimal with hundredths place value, round it to the nearest tenths.

4. Prerequisite skills. Specify prerequisite skills that a learner would need to have that may not be part of the topic scope. The prerequisites should also include specific skills from previous lessons in the series. These will be used to generate random review questions at the start of each lesson to determine whether the student has indeed mastered the skills they need for the present topic.

5. Acquired skills. List all the skills that learners will acquire by the end of the lesson.

Creating Questions for Skills

Questions for skill practice can either be created directly by Topic Managers and Admins or suggested from contributors to Oppia. When creating questions, ensure that:

• All misconceptions attached to the skill have been addressed in the answer groups.

• Questions include hints and solutions.

• Questions are varied and there is no visible pattern among them like the answer always being option ‘a’, for example.

• There are more questions for harder skills.

• Questions are as challenging and complex as they need to be if preceded by sufficient explanation.

• At least one of the answer groups is marked as correct.

• Questions are framed with simplicity and brevity—sticking closely with the skill being taught and not getting lost in the story details.

Developing a Story Outline

Usually a topic will have one story that will span across different lessons. At this stage, you will draft a high-level story for each lesson. As far as possible, try to make the content universal and free from culture or country-specific references.

Stories are what make Oppia lessons so engaging for learners. You don’t have to overdo it with the story details and plot—after all, the concept being taught should be driving the lessons forward. You want just enough of a story arc to keep learners engaged and empathetic with your main character. Like any good story, there should be a challenge for your protagonist (a possible trap or misconception) that they overcome; with the learner also feeling that accomplishment by the end of the lesson.

A good way to approach this step is to think of a practical, real-world setting that best demonstrates the concept being taught, and that learners will be able to relate to. Following this, create characters that are human as opposed to animal-like to reflect a more realistic setting and ensure that you ground learners in an explanation before moving on to its application.

Example

A good real-world example for Decimals is expressing time in hours, minutes and seconds. A story emanating from this idea might be a young child who has been tasked with recording the swim time of her competing classmates using a stopwatch. This setting might span several lessons as the character learns how to read the resulting times, connect the tenths and hundredths place values to minutes and seconds, compare decimal place values and so on.

Your high-level story outline will include:

• A brief overview of the characters, settings and premise.

• One to two paragraphs describing what happens in each lesson.

Developing a Chapter Outline

Chapter outlines will serve as a guide for lesson creators when creating an exploration for that chapter. The outlines will

• inform as to what the exploration should contain,

• ensure that explorations have a unified theme, and

• have prerequisite and acquired skills for each lesson clearly described.

Creating a new skill

In this section, you will learn how to:

• Create a new skill

• Write the Concept Card for a skill

Watch this video to learn how to create a skill, or if you prefer reading the instructions instead, keep scrolling down.

Creating a new skill

1. From the Topics and Skills Dashboard, click the button.

2. The Create New Skill dialog box appears. Enter a description for the new skill under New Skill Description.

3. To enter a rubric for a difficulty level, first select the difficulty level under Add Skill Rubrics and then enter the rubric in the text box below.

Rubrics

Rubrics help question creators when they create questions for the skill. You can enter rubrics for each difficulty level of the skill (Easy, Medium, Hard) which are then shown to question creators so they know what the question should test. For example, in the image below, if a question creator chooses to create an easy question for this new skill, this rubric will be shown as a guide to creating the question:

Fig. 1

You may enter multiple rubrics by clicking the first button below the text box and selecting the next level of difficulty.

3. When you are done entering all rubrics, click and you will be directed to the Skill Editor screen.

Writing the Concept Card for a skill

Concept Cards

The Skill Editor shows you three cards in addition to the ones mentioned above. The Review Material and Worked Examples sections are together known as ‘Concept Card’. The information you enter here is what a learner will see if they have trouble answering questions related to the skill. In other words, enter information here that will help a learner understand the skill concept better by providing a brief explanation of how to perform that skill, and some examples.

Misconception card

The Misconceptions card is useful for question creators to ensure that they address all misconceptions when creating questions and answer groups for that skill. The information you enter here will help ensure that answer groups have a sufficient amount of targeted feedback.

Fig. 2

1. When you have entered all the details, to return back to the Topics and Skills Dashboard without publishing the skill, select the dashboard from the drop-down menu on your username picture in the top-right corner of the screen. This will create a tab called Unpublished Skills which lists all skills created and not yet published.

2. To publish the skill right away, click the button, and then . This will create a tab called Unused Skills which lists all skills published and not yet assigned to any Topic.

Attention

You won’t be able to publish a skill until the Skill Description and Review Material fields are filled out. While the other fields are not mandatory, they should still be filled out to enhance learner experience.

Fig. 3

3. To edit the Concept Card, Misconceptions and Rubrics for a skill at any time, click on the skill under the Unpublished Skills or Unused Skills tabs.

4. To delete an unused or unpublished skill, click the button to the right of the skill.

Creating a new topic

In this section, you will learn how to:

• Create a new topic

• Create a new story

• Create a new chapter

• Import an exploration in a chapter

Watch this video to learn how to create a skill, or if you prefer reading the instructions instead, keep scrolling down.

Creating a new topic

1. To create a new topic, click the button at the top of the Topic and Skills Dashboard.

2. Enter a name for the topic and click . You will be taken to the Topic Editor screen, where you can give your topic a description.

Fig. 1

3. To save a draft of the topic, click on . This will list the topic in the dashboard with a ‘Not Published’ status.

4. To publish the topic, click the button. This will list the topic in the dashboard with a ‘Published’ status.

5. To delete the topic, click the button to the right of the topic.

Fig. 2

Creating a new story

1. To create a new story, click from the Topic Editor screen.

2. Enter a title for the story and click . You will be taken to the editor screen, where you can give your story a description.

Fig. 3

3. To save a draft of the story, click on . You can return back to the Topic Editor which will keep the story in a draft status.

4. To publish the story, click the button. This will list the story in the Topic Editor with a ‘Published’ status.

Creating a new chapter

1. To create a new chapter for the story, click within the story editing screen.

2. Enter a title for the chapter and click .

Importing an exploration

When you create a chapter, you will see the following fields:

• Chapter Outline: Enter a description of what the lesson will entail. This will guide exploration creators when they create the lesson.

• Exploration ID: Import a published exploration by entering its ID. You will not be able to publish the story or save changes to your chapter without completing this step.

• Prerequisite Skill IDs: Select prerequisite skills for this lesson based on those identified in the Skill Tree by clicking .

• Acquired Skill IDs: Select acquired skills for this lesson based on those identified in the Skill Tree by clicking .

• New Chapter: Click to create a new chapter for the story. As you create chapters, they are shown as a list on the left-hand side. Click on the new chapter here to import another exploration and select skills. Continue adding new chapters as needed for this story.

Finally, click and when done.

Fig. 4

Assigning a skill

In this section, you will learn how to:

• Assign a skill to a topic

• Assign a skill to a subtopic

• Create a question for a skill

Watch this video to learn how to assign skills, or if you prefer reading the instructions instead, keep scrolling down.

Assigning a skill to a topic

When you initially create and publish a skill, it falls under the category of Unused Skills until you assign it to a topic.

Fig 1.

1. To assign a skill to a topic, click the Assign to Topic button next to the skill.

2. Select the Topic to which you want to assign the skill and click . As you assign skills, they are taken out of the Unused Skills tab and added to the topic.

3. To merge an unused skill with a skill already assigned to a topic, click the Merge Skill button next to the skill, and select the skill you want to merge with.

Fig. 2

4. Once a skill is assigned to a topic, it can now be added to a chapter within the topic. To add a skill to a chapter, click on the topic, then the story title.

5. To add prerequisite and acquired skills to a chapter, click on and to select from the list of assigned skills.

Fig. 3

6. Skills are now added to this chapter. Save your changes when done.

Fig. 4

Assigning a skill to a subtopic

When you initially assign a skill to a topic, it falls under the category of Uncategorized Skills. This means that they have not yet been assigned to any subtopic.

To enable learners to review the skills associated with a topic, you will need to create subtopics and then assign skills to the subtopics. When learners begin a practice session, they will choose the subtopic they want to practice and then review the skills within that subtopic.

1. To create a subtopic, click on the topic and then the Subtopics editor button in the top-right corner.

2. To create a new subtopic, click on + Add Subtopic, enter a title and click .

3. To assign skills to a subtopic, drag the skill from the list of Uncategorized Skills on the right side and drop it under the relevant subtopic. To remove a skill from the subtopic, drag the skill back to the Uncategorized Skills list.

Fig. 5

4. To unassign a skill from a topic, click the button next to the skill in the Uncategorized Skills list. This will not delete the skill, but move it back to the Unused Skills tab in the Topics and Skills dashboard.

5. To delete a subtopic, click the red X next to the Subtopic Title. This moves any associated skills back to the Uncategorized Skills list.

6. To create a high-level description for the subtopic that learners will see in the practice session, click the button next to the Subtopic Title. Enter the description in the text box under Subtopic Page. This will help learners decide which subtopics to practice.

Important

Ensure that each subtopic contains a unique list of skills, i.e., skills are not repeated in different subtopics.

7. When you have finished creating subtopics and assigning skills to them, click .

Creating a question for a skill

Questions can be created either through the Topic Editor or submitted by contributors.

1. To create a question from the Topic Editor, click on the topic, and then the Questions Editor button in the top-right corner.

2. Click the Create Question button.

3. Select one or more skills for which you want to create the question and click Next.

Fig. 6

4. Select the question’s level of difficulty—Easy, Medium or Hard—and click Done. If there were rubrics written for these levels when the skill was created, you will see them here.

5. The Question Editor box opens. This works just like an Exploration Editor where you can create questions, add interactions, responses and feedback. At least one of the answer groups must be marked as correct. You also have to add a hint in order to publish the question. For some interactions like Text Input, you will be required to add a solution to the hint, which must correspond with one of the correct answer groups.

When you have finished creating the question, click .

Fig. 7

6. To change the published question’s level of difficulty, click the button and select a different level.

7. To delete the question, click the button.

Reviewing Lesson Contributions

Reviewing is critical in ensuring that the translations, questions and voiceovers submitted by the contributors are correct and error-free. In order to review questions, translations or voiceovers, a user must be authorized by the admin.

The review rights of a user are listed in the header of the Contributor Dashboard under the My Contributions tab. Review rights for translations and voiceovers are language specific whereas those for questions are not. The languages in which you can review translations and voiceovers are also listed in the header.

The left sidebar shows options to review according to rights that you have.

Fig. 1

This section will cover how you can review:

• Translations

• Voiceovers

• Questions

Reviewing Translations

Oppia’s lessons are translated to multiple languages to ensure a wide range of students across the world can learn in their own language. After translations are submitted, they are sent for review. As a reviewer, you can review all the translations in the language for which you have review rights.

To start reviewing the translations:

1. Click on in the left sidebar to see the list of all the available translations awaiting review.

Fig. 1

2. Select the translation you want to review buy clicking on the button of that particular translation. A translation review modal will open up as shown in the figure.

Fig. 2

3. The left side text box contains the original text in English and the right side text box contains the translated text. Check if the translation is gramatically correct and conveys the same meaning as the original text. Please follow the guidelines.

4. If you do not want to review, click on the button to close the modal.

5. If the translation is correct, click on the button to approve it and review the next translation. Adding a review message is not mandatory when accepting a translation.

6. If the translation is not correct, type a review message in the text box with the label ‘Review message’ explaining the reason for rejection and any possible improvements and suggestions. This message would be visible to the translator. Note that you cannot reject a translation without a review message. Click on the button to continue reviewing other translations.

Fig. 3

7. Continue the same procedure untill you have completed reviewing all the translations.

Guiding Principles

To ensure that translations convey the same meaning as the original text, please keep these principles in mind:

• Ensure that the the voice and meaning of the original text is preserved. It doesn’t mean you have to accept only literal translations. If the language is natural, understandable and stays close to the source, the translation is worth accepting.

• Ensure that all of the meaning in the original text is present in the translation.

• Ensure that the translation choices are consistent.

• Ensure that no information is added or subtracted during the translation.

• Ensure that there are no gramatical errors or spelling mistakes in the translation.

Note: While reviewing a translation, if you see broken images, do not accept the translation.

Reviewing Voiceovers

To be updated soon!

Reviewing Questions

To be updated soon!