Oppia project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
Technical writer:
Project name:
Beginners’ guide to creating lessons and associated material on Oppia
Project length:
Standard length (3 months)

Project description

Why Oppia?

I have a keen interest in education and learning having worked as a teacher in the past. Oppia’s online interactive learning is a great way for tutors to get creative and reach out to students in an engaging learning environment and enable learners from all over the world to gain access to this resource. I would love to be a part of this global community by contributing to the documentation for this site.

Why this project?

As online learning increases in popularity around the world, there is a need for platforms that are easy to use and manage - not just for the student, but also the tutor. Oppia is one such interactive learning platform whose aim is to recreate a one-on-one learning scenario in an engaging manner online. The key to success in a platform like Oppia is for the education provider to be able to create effective learning units or ‘explorations’ that allows for interactivity, dialogue and feedback. The educator’s role does not end here - once the lesson is published, there is also room for enhancing the exploration based on learners’ interactions and feedback.

Creating a beginner’s guide for Oppia while addressing these needs will be a great way to combine my technical writing skills with a topic I am passionate about - education. I have just completed a Certificate in Technical Communication where I worked on projects with an intense focus on user experience, digital media and information architecture, and this project will enable me to use the skills I have acquired during the program.

Project Plan and implementation


Education providers on Oppia need clear and accessible tools and information to be able to create explorations - this is where comprehensive documentation comes in. They need to understand the more complex tasks of improving their exploration as well. Accessible and concise documentation will lead to a satisfying user experience.

As users have different learning styles, a combination of written guides and video tutorials is proposed. Video tutorials are appealing to visual learners and as the videos will be specific to a particular task, users will be able to get the information they need quickly.

Audience analysis

The audience for this project are those who want to create explorations or learning units. Users are anyone with an interest in teaching - these might include classroom teachers, tutors, retirees who wish to share their experience and knowledge, students themselves who wish to teach others, volunteers, professors etc. The tasks that these different users will perform on Oppia will depend on their role and what they want to achieve with Oppia. Qualified teachers might want to create more comprehensive explorations than a student who wants to explain a difficult concept to their peer.

Users will have a variety of skills - ranging from novices to experts in their fields. As this particular project is focusing on guides that move beyond the basics, i.e. towards more complex tasks - the groups using these guides the most would be intermediates and experts. Thus the guides should cater to this range and provide fast-path information for experts.

Level of Expertise: Intermediate

Concepts: Needs to understand more complex concepts such as rules, characterization etc.

Tasks: Is more interested in more complex tasks such as adding voiceovers, images, adding branches to an exploration etc. Has created lesson plans before, but not necessarily an interactive plan on Oppia.

References: This group will need a moderate amount of documentation.

Level of Expertise: Expert

Concepts: Needs to understand more advanced concepts such as parameters, embedding etc.

Tasks: Needs to learn how to match their teaching expertise to Oppia, or if they already know Oppia, figure out any new tasks that might have come with a new update. This group is also more interested in complex tasks such as using the History or Stats tabs effectively.

References: Has worked with Oppia before, or is very well-versed with a similar learning platform. Professional knowledge in teaching and creating effective lesson plans. This group will need the least amount of documentation.

User Task Analysis

  1. Planning an Exploration:

    • Creating a story outline
    • Planning an exploration around the outline
    • Planning assessment methods

    Example: Neil is a teacher using Oppia for the first time. Before he begins working in Oppia, Neil will have to plan what his learning outcome or goal for this particular exploration is. Then he will have to think of an engaging scenario to build the lesson around. This will build up the learner’s interest.

    When planning the exploration, Neil will remember to begin with a simple linear exploration because he knows he can build in complexity later. He will think of how to present explanations and test his learner’s understanding. Based on the learner’s responses, Neil will have to think of how to present feedback and advance through the exploration.

    Once Neil has a basic outline of what his exploration will entail, he can begin working in Oppia.

  2. Adding voiceovers to a lesson (using the Translation tab): Neil can also add voiceovers to his cards or translate them to another language. If he wants to add voiceovers in another language, Neil will first have to translate his card into that language, following which he can then add a voiceover.

  3. Using the History tab: He has the option of reverting to an older saved version of the exploration via the History tab - with this tab Neil can also download and save an older version.

  4. Using the Feedback tab: Learners have the option at any time to leave feedback as they move through an exploration. Neil can view this feedback and use it to help improve his lesson. He can reply to messages, and has several options for changing the status of the message (fixed, not actionable etc.)

  5. Enhancing a lesson through stats and playthroughs (using the Stats tab): When Neil has published his exploration and has different learners working on it, he will want to use learner’s interactions to improve his exploration. He has a few options for enhancing his lesson.

    He can start to build more complexity into his exploration by creating branches that will eventually lead back into the main branch he had created earlier. He may provide shortcuts for more advanced learners - this will prevent boredom and increase their engagement levels. He might think about using parameters which will customize the exploration to a particular learner for that playthrough.

  6. Adding images, videos: Neil can also add images, videos, links while creating a particular card.

  7. Inviting other users to an exploration: Neil can invite other users to his exploration and assign them different roles of:

    • Manager
    • Collaborator
    • Translator
    • Playtester

    Each role can control the functions of the roles beneath it, so the Manager role has the most functionality. Since Neil has created this exploration, he is given the role of ‘Manager’ in Oppia.

Proposed guides (based on User Task Analysis)

Planning a lesson

  • Creating a story outline / scenario
  • Structuring a scenario-based lesson
  • Planning assessment methods (including how to write practice questions)

Adding voiceovers to a lesson (using the Translation tab)

  • Adding voiceovers in the original lesson language
  • Adding voiceovers in a different language

    • Translating text in a card *Recording voiceover in the second language

Using the Stats, History and Feedback tabs effectively

Formatting lesson content with images, videos, links etc.

Enhancing a Lesson using Stats and Playthroughs

  • Adding branches to an existing lesson
  • Creating shortcuts for more advanced learners

Inviting other users to a lesson (roles)

  • Role types and their hierarchy



Oppia’s documentation lends itself well to a combination of written guides and video tutorials (see Sample Guide section below for an example). This caters to different learning styles and provide more options for users to learn how Oppia works.


The project will consist of a user guide and video tutorials. The guide and videos will cover the the content detailed in the Proposed Guides section above with an exception (the first guide Planning a lesson will not require a video). The videos will be embedded within the page covering a user task.

Weekly Milestones:

The development phase runs from September 2 - November 22, 2019.

Week 1, 2 and 3 (Sep 2-20):

Planning a lesson (Creating a story outline / scenario, Structuring a scenario-based lesson, Planning assessment methods (including how to write practice questions)

Week 4 (Sep 23-27):

Adding voiceovers to a lesson

Week 5, 6 and 7 (Sep 20-Oct 18):

Using the Stats, History and Feedback tabs effectively

Week 8 (Oct 21-25):

Formatting lesson content with images, videos, links etc., Inviting other users to a lesson (roles)

Week 9, 10 and 11 (Oct 28-Nov 15):

Enhancing a Lesson using Stats and Playthroughs

Week 12 (Nov 18-22):

Review and modifications

Sample guide and video tutorial



I propose continuing to use GitHub pages where Oppia currently hosts its documentation. As Github doesn’t allow for embedding videos, the only workaround is to insert an image that links to a video as demonstrated in the Sample guide above.

Other Commitments

I will be in the Eastern Daylight Time (EDT) zone during the implementation phase of this project. I can commit to the entire duration of the project, i.e. until November-end.


The frequency of contact will be dependent on a discussion with the mentor. I prefer regular communication - my suggestion is once every two weeks to provide an update and receive feedback on work done so far. However, this is flexible depending on the mentor’s preference as well.