Reviving 100+ page user documentation into a unified database
About Oppia
Oppia is a free open-source learning platform that serves over 1,000,000+ users. They allow anyone with an internet connection to learn basic concepts or create lessons that are hosted on the platform.
Challenge and approach
Oppia originally used two separate documents, the User Guide and User Documentation to help different roles create, maintain, or use the content on their platform, which can lead to confusion, mismanagement, and difficulty adding future updates. In addition, both documents are 3+ years out-of-date. There are missing features, new flows, entire new pages that are not reflected in either current documents.
1
Challenge
How do we combine two seperate sources of truth?
Approach
I created a system to label overlaps and gaps in content
Created a spreadsheet labeling which entries are relevant, irrelevant, incomplete, or duplicated. I also included actionable advice to fuel the direction for the entry.
Labeled and assigned remaining entries across myself and other writer.
2
Challenge
How to we ensure the content is updated efficently and accurately?
Approach
I created a checklist to track granular progress of each entry and project checkpoints
Designed and implemented a new style guide specific to this project revolving around technical writing standards.
Each entry had its own checklist and requirements to meet a certain standard including insuring all content was updated, abided by the technical writing style guide, and was edited by both myself and the other writer.
An excerpt from the user documentation
The clearest and most tangible way to improve the technical documentation is to update, re-organize and clean up the clutter on the most fundamental aspect of the internal documentation at Oppia: building lessons.
Current lesson content organization is confusing and scattered
Currently there are two seperate sources of truth each with competing goals and information. The first is referred to as the User guide, the second is left untitled (I will refer to it as user documentation).
User guide content
How to:
Access the Exploration Editor
Write an introduction
Create cards (the building blocks of each lesson)
Edit and publish a lesson
How to:
Create a lesson plan
Access the Exploration Editor
Identify the four parts of a card (the building blocks of each lesson)
publish a lesson
Updated lesson content is unified and authoritative
Now, there is one authoritative content with all relevant information, updated to reflect the current platform.
User documentation
How to:
Plan lesson content
Create an introduction
Create a new card
Build lesson cards
End a lesson
Publish and save a lesson
Content comparison
Here are a few sample excerpts from both the current and new versions:
Content before
Results
Now, there is one authoritative content with all relevant information, updated to reflect the current platform.
What I learned
Now, there is one authoritative content with all relevant information, updated to reflect the current platform.