Contents
Project Summary
Project Details
Name: Beginners’ guide to creating lessons and associated material on Oppia
Oppia is an open-source learning platform that allows for creation and sharing of interactive lessons. The organization is launching new lesson creation and contribution workflows for its platform which includes new features and additional dashboards. The goal is to enable lesson creators to build high-quality lessons that are related to specific topics. In addition, contributors are now able to improve lessons by submitting translations, voiceovers, digital art and review questions.
This new workflow introduces new dashboards and processes that were not yet documented. The documentation can be divided into three groups based on the three audience groups identified for this project:
- Lesson Creators
- Topic Managers and Administrators
- Contributors
Season of Docs
During the Doc Development phase, I collaborated with developers and documented the new processes and interfaces described above for the three user groups. I was given the freedom to choose a hosting platform for the new documentation and decided on Read the Docs for the following reasons:
- Consistently high ranking in sites comparing different hosting platforms.
- Largest open source documentation hosting site in the world.
- Automatically updates documentation each time a commit is made to the source code.
- Relatively easy setup compared to other hosting platforms that required heavy usage of the command line. Read the Docs involves creating an account and then pointing it to a publicly hosted repository.
- More troubleshooting support online due to the popularity and extensive usage of Read the Docs.
Using Read the Docs involved documenting using the Sphinx python module. Documents were written using a markup language called reStructuredText and included a written user guide as well as video tutorials for each task identified in the new workflow.
Subsequently, Oppia created a new repository to store the docs.
Work Status
Completed
The repository lists the pull requests I have authored during Season of Docs which will serve as the source for documentation to be hosted on the Read the Docs platform. With reference to the three user groups, documentation for Lesson Creators and Topic Managers/Administrators is complete.
Remaining
1. The Contributor Dashboard is still undergoing development, therefore the documentation aimed for Contributors is not yet complete. There are four areas for contributing:
- Translations (completed)
- Voiceovers (in progress)
- Questions (in progress)
- Digital art (not yet developed)
2. Creating a Read the Docs account and linking the repository to it for hosting.
Highlights
New Skills Learned: The project was an opportunity to pick up new skills, in particular:
- Learning the process flow in GitHub.
- Using git commands to sync my local clone of the repository with the original, commit docs, and submit/amend pull requests.
- Documenting using Sphinx, writing in reStructuredText, and then hosting on the Read the Docs platform.
- Getting a glimpse into how developers work and plan a new product.
Frequent communication: Weekly meetings with mentors made me feel supported as I knew any question or doubt would be addressed, or any issue would be dealt with. I received quick responses from developers on product features.
Freedom to choose hosting platform and independence over creating documentation.
Opportunity to continue being involved with the project after Season of Docs with more networking opportunities.
Problems and Challenges
- Initially, there was a steep learning curve as I learned the basics of writing in a new markup language (reST), running a local build, and submitting a pull request. It took a lot of time to do a single step due to the unfamiliarity. This was no longer an issue by Week 4 of the project.
- Sometimes it was challenging to know what search terms to use when troubleshooting to get effective search results. For example, the first time I sent a pull request and had to make changes before it could be merged, I was searching for terms like ‘updating a pull request’ before later realizing the correct terminology was ‘amending a commit’.