Season of docs 2019
Table of Contents
Oppia is planning to participate in the first year of the Season of Docs program! This program connects open source organizations with technical writers, who work on 3 or 6 month long projects, and receive a paid stipend for doing so. The technical writers work closely with two or more mentors on finishing a project idea by the organization, or on a proposal of their own.
Please note that acceptance into Season of Docs isn’t a prerequisite for becoming an Oppia contributor. The Oppia project is run by the community for the community, and we warmly welcome anyone who’d like to help out!
Getting started
If you’re interested in applying to work with Oppia for Season of Docs, please follow these steps:
Sign up to the oppia-sod-announce@ mailing list in order to receive important notifications about Oppia’s participation in Season of Docs. If you like, you can also sign up to the oppia-sod-discuss@ mailing list to participate in general discussion related to Oppia’s involvement in Season of Docs. Make sure to set your mailing list preferences correctly so that you actually get the emails!
Get a better understanding of what Oppia is all about by taking a look at our user documentation — this will help you become familiar with important concepts like explorations and interactions. We also recommend having a go at playing some of the existing lessons on Oppia.org, like these ones on Fractions, to get a better idea of what they look like.
If you think that you’re familiar enough with Oppia, select one or more Season of Docs projects that you’re most interested in, and write your project proposal! We strongly encourage you to discuss your project ideas and share your proposal with the community, so that you can get feedback and ensure that what you’re writing makes sense to others. The best way to do this is to put your proposal into a collaborative editing tool like Google Docs, allow others to comment on it, and share a link to it on the Season of Docs discussion mailing list. You can also email this mailing list if you have any questions about a project, or would like to discuss your approach with the Oppia community and get feedback. Please be specific when asking questions, since this makes it easier for us to help you. You can also start working on one of the starter projects.
FAQ
Q: How can I increase my chances of getting selected?
A: Writing a good project proposal, engaging with the community, helping other students, successfully contributing to already existing documentation (Technical documentation and User documentation), and demonstrating that you can work independently can all help you. You can also propose some more ambitious projects and changes that we might want to implement in our documentation.
Starter projects
For each project that we have, you can pick one of two starter projects to work on, these will be evaluated together with your project proposal and should basically present us how will the other pages/guides/docs look like if you get accepted for Season of Docs 2019. You should primary focus on quality and not quantity. The starter projects will be evaluated from two main perspectives:
if the project is correct from the technical point of view (it says only things that are true)
if the project is grammatically and typografically “correct” (if it is easy to understand)
You can submit the starter project into oppia-sod-discuss@ before the deadline for project proposals (June 28).
Beginners’ guide to creating lessons and associated material on Oppia
Guide about how to use the “translation tab” of the exploration editor effectively.
Guide about how to enhance a lesson based on the information provided by stats and playthroughs.
Guide for Oppia developers
Guide about how to write a backend job.
Guide about how to write good frontend tests
Descriptive “how it works” docs for the Oppia codebase
Documentation about the life-cycle of a request/response
Documentation about the build process
Season of Docs Proposal
Important: Please make sure that your final proposal is self-contained! In particular, to be fair to all applicants, key components of the proposal should not be editable after the deadline, and you shouldn’t assume that reviewers will follow external links.
Template
When submitting a proposal, please use the following template:
Project Details
Name of the project.
Why are you interested in working with Oppia?
What interests you about this project?
Project plan and implementation strategy. This is the most important section of the proposal.
The platform you want to use for hosting the documentation
Other Commitments
Which timezone(s) will you primarily be in during the implementation phase?
How much time will you be able to commit to this project?
Communication
What is your contact information, and preferred method of communication?
How often, and through which channel(s), do you plan on communicating with your mentor?
Tips for writing a good project plan
The plan should include milestones that divide your work into multiple parts. You can set monthly or weekly milestones. Strong proposals will have clear, concrete and measurable milestones, whose success can be objectively evaluated by an external observer.
The plan should include a breakdown of the pages/guides/how-tos that you plan to write, possibly including rough drafts or samples. For guides, you might want to make a list of steps that the guide should include, and what files the guide should reference.
Selection criteria
In order to select technical writers for Season of Docs, we will mainly be looking at three things:
The quality of the submitted proposal
The quality of the applicant’s previous technical writing related work
The quality of the applicant’s starter project
We believe that strong performance in these dimensions is likely to correlate well with the technical writer having an enjoyable, fulfilling and productive experience over the summer, and successfully completing the Season of Docs program.
For the proposal, we generally look for a clear indication that the technical writer has a good, deep understanding of the project. Some indicators that could help with this include:
Clear, unambiguous communication.
A clear analysis of (and good design decisions that build on top of) the original project idea, with a strong focus on creating clear and understandable documentation for users or developers.
A concrete, specific breakdown of the work to be done for each milestone.
A proposal that is sufficiently concrete to demonstrate that the applicant is familiar with the scope of the problem they’re tackling. This may include pointers to parts of the Oppia codebase.
Project ideas
Beginners’ guide to creating lessons and associated material on Oppia
This is a guide for new Oppia lesson creators about lessons/explorations, skills, lesson translations, and the interface of the Oppia page. Currently our user documentation is hosted on the oppia.github.io pages, but if you prefer to host the documentation on a different platform, you can explain that in your proposal.
List of guides to write
How to organize skills and create a story outline for a topic.
How to create a lesson that fits in a story.
How to use the “translation tab”, “stats tab”, “history tab” and “feedback tab” of the exploration editor effectively.
How to enhance a lesson based on the information provided by stats and playthroughs.
How to translate or add voiceovers to a lesson.
How to add images to a lesson (including alt text for accessibility).
How to write practice questions for a skill.
How to set the roles for an exploration, and how the roles system works (including the hierarchy and the rights of each role).
Knowledge/Skills needed
Technical writing experience
Guide for Oppia developers
This involves organizing the information architecture of the Oppia wiki, and fleshing it out with additional short guides for Oppia developers in the form of “how-tos” which provide useful resources for new but also experienced developers. The aim is to answer all questions that Oppia developers regularly face in their work, so part of this project would also involve monitoring discussions on Gitter and PRs to see which issues tend to come up frequently, and address those. Some examples:
How to install and start Oppia
How to deploy Oppia on Google App Engine
How to write a backend job
How to write, test and run a migration
How to create a new interaction type
How to write good backend tests
How to write good frontend tests
How to write good end-to-end tests
How to write a new lint check
How to write code that is effective and doesn’t affect the page speed
How to upgrade third party library
Onboarding guide for the QA team
Onboarding guide for the onboarding team
Knowledge/Skills needed
technical writing experience
slight knowledge of Python
slight knowledge of Angular
Descriptive “how it works” docs for the Oppia codebase
This involves creating documentation for the Oppia codebase that explains the structure of our frontend and backend. It could extend some of our already-existing wiki pages, but if you prefer a different platform to host the documentation, you can explain that in your proposal.
Places in codebase to explain
Overview of the codebase, including:
frontend
backend
build process
the life-cycle of a request/response (see the TODO at the bottom of this wiki page)
How is our data stored
images
explorations, skills, questions, topic
feedback, suggestion
users
How are various extensions structured
rich_text_components
interactions
visualizations
issues and actions
schema-based editors
object editors
Knowledge/Skills needed
technical writing experience
slight knowledge of Python
slight knowledge of Angular
Other useful information
Dates and Deadlines
Mar 16 – Apr 23: Organizations apply
Apr 30: Organizations are announced
Apr 30 – Jun 28: Technical writers application period
Jul 30: Accepted technical writers are announced
Aug 1 – Sep 1: Community bonding period
Sep 2 – Nov 29: Technical writers create documentation to their projects (short-running project)
Sep 2 – Feb 21 (2020): Technical writers create documentation to their projects (long-running project)
List of Potential Mentors
Sandeep (@DubeySandeep)
Sean (@seanlip)
Vibhor (@vibhor98)
Vojta (@vojtechjelinek)
Communication
Chat
Oppia has a real-time chat channel on Gitter! You can log in using your GitHub account (Gitter will ask to be associated with your GitHub account for authentication) and you will then be able to talk in it. Please feel free to use Gitter if you just want to say hi to the community or if you have any questions related to getting started.
Email
If you have questions pertaining to “how-to-get-started”, please ask them on Gitter, or the oppia-dev@ mailing list. Please be specific when asking questions; this makes it easier for us to help you.