Season of Docs 2024

Table of Contents

• Timeline
• Getting started
• FAQ
• Starter projects
• SoD Statement of Interest
  • Template
  • Selection criteria
  • How to apply?
• Project Idea
• List of Org Admins
• Communication

Note

Oppia was not accepted for Season of Docs 2024.

Oppia is planning to participate in the Season of Docs 2024 program! This program provides support for open source projects to improve their documentation and gives professional technical writers an opportunity to gain experience in open source. The technical writers work closely with one or more mentors on finishing a project idea given by the organization.

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!

The program timeline

Please see the Season of Docs timeline here: https://developers.google.com/season-of-docs/docs/timeline.

In addition to the dates provided there, Oppia will follow the timeline below:

25 Mar - 5 Apr 2024 Proposal submission: Technical writers are expected to submit their "Statement of interest" in PDF format through the google form before the deadline to show their interest in the project. Org admins will reach out to shortlisted technical writers by 12 Apr 2024.

Selection announcement: We expect to announce the selected technical writer on oppia-sod-announce@ on or before 30 Apr 2024 at 18:00 UTC. Note that this is conditional on Oppia being accepted to the Summer of Docs program for 2024 (the results of which will be announced by Google on 10 Apr 2024 at 18:00 UTC).

Getting started

If you're interested in applying to work with Oppia for Season of Docs, please follow these steps:

1. Read and become familiar with the requirements in Google's Technical Writer Guide.

2. Read and follow the instructions to sign the CLA and fill up the survey form carefully.

3. 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!

4. 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. You might also like to follow the guidance on the Getting Started wiki page to become familiar with the Oppia codebase, and take up a starter issue if you are able to do so.

5. 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 statement of interest! You can also email the Season of Docs discussion mailing list if you have 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.

• Note: If you like, you can also start working on one of the starter projects. This will help us better understand the sort of work you are able to do, as well as whether you're able to work using the technologies that we use for Oppia's code and documentation.

1. When you're ready, submit your application to our application form following the guidelines below.

FAQ

Q: How can I increase my chances of getting selected?

A: Writing a good project proposal, engaging with the community, helping other applicants, successfully contributing to already-existing documentation, gaining and showing familiarity with the parts of Oppia you propose to document, and demonstrating that you can work independently can all help you.

Starter projects

Address any issue on the Oppia wiki repository

The aim of this project is to tackle any documentation issue on the Oppia wiki repository. It's fine to take up any issue mentioned there, though we recommend that you prioritize the issues that are marked as higher-impact over the other ones.

Steps to follow:

• View the documentation issue tracker at https://github.com/oppia/oppia-web-developer-docs/issues
• Find an issue you're interested in tackling, and make sure you understand clearly what needs to be done. Dig into the main Oppia documentation and codebase as needed to get the necessary information to tackle the issue.
• Read these instructions for how to tackle a good first issue at Oppia. Following the instructions, leave a clear comment in the issue discussion thread explaining what you are planning to do, and demonstrating that you have sufficient understanding of the issue in order to tackle it.
• While waiting to be assigned, consider creating a draft pull request that you can submit as soon as you're assigned to the issue.
• Once you have been assigned, follow the instructions in Rules for making PRs to submit your pull request. (Note that this wiki page describes making PRs to oppia/oppia, and you might need to adjust the instructions as needed to make your PR to oppia-web-developer-docs instead.) Address any reviewer comments until your PR gets approved and merged.

Document your process of installing Oppia and attempting a starter issue

The aim of this project is to create a case study of your experience installing Oppia locally and tackling a coding issue. This helps you gain empathy with the audience of your documentation (i.e. Oppia developers) and helps identify issues with the existing onboarding flow that need to be improved.

Steps to follow:

• Follow the instructions on the Getting Started page to set up Oppia locally on your machine and tackle a starter issue. Maintain a doc/journal describing your experience, any roadblocks you encountered, and how you overcame these roadblocks.
• Feel free to open issues or questions on GitHub Discussions if you need help. Make sure that you provide sufficient context to help responders answer your questions. For guidance on asking questions, see our wiki page on getting help.
• Think about how you might address these roadblocks so that other contributors do not encounter them, and include a section in your doc specifying what changes you would make (if any) to Oppia's onboarding guides and general documentation.
• Submit a link to your doc/journal as part of your statement of interest.

SoD Statement of Interest

Important: Please make sure that your final statement of interest 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 (except for those describing contributions to previous documentation projects, including starter projects).

Template

When submitting a proposal, please use the provided SoD statement of interest template. This template contains additional Oppia-specific guidance for Season of Docs, so be sure to read it carefully!

Selection criteria

In order to select technical writers for the project, we will mainly be looking at three things:

• The quality of the submitted statement of interest
• The quality of the applicant's previous technical writing-related work
• The quality of the applicant's starter project submissions, if any

We believe that strong performance in these dimensions is likely to correlate well with the technical writer having an enjoyable, fulfilling, and productive experience, and successfully completing the project.

For the "Statement of interest", 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 the original project idea, with a strong focus on creating clear and understandable documentation for users or developers. The proposal should be sufficiently concrete to demonstrate that the applicant is familiar with the scope of the problem they're tackling, and may include pointers to parts of the Oppia codebase.
• A concrete, specific breakdown of the work to be done for each milestone.

How to apply?

Applicants are expected to fill up the application form and upload the final "Statement of interest (SOI)" in PDF format before the deadline. If you fail to submit the form before the deadline, then we will not be able to accept your application.

You may optionally submit draft SOIs to the org admins for pre-submission review. Please draft your SOI in Google Docs and send an email to the org admins at [email protected] with a link to your draft. The org admins will review your draft and make suggestions to help you improve your SOI. Please make sure you give everyone with the link permission to comment so that we can give you feedback! Pre-submission is completely optional, and we may not be able to respond to everyone's drafts. Please do not risk missing the submission deadline, even if you are waiting for feedback.

Per the guidance in the official Season of Docs guide, we will reach out directly if we would like to work with you or discuss your statement of interest further.

Project Idea

Develop tutorials to help contributors tackle issues in new domains

Problem statement

The Oppia project has a large technical community, comprising numerous open-source contributors from around the world. However, we have been seeing that quite a number of contributors who sign up to start contributing to Oppia are having trouble getting started on their first issue.

While there is plenty of documentation on the wiki that outlines the basic steps of how to get started and run tests etc., we are concerned that new contributors may not have enough support to map the documentation to the next step in their development journey after they get Oppia set up locally. After an analysis of our documentation using the Diátaxis framework, we believe that part of the issue is that our documentation has a significant lack of tutorials. The aim of this project is to remedy this.

Project’s scope

This project involves three parts. Most of the work for the project is contained in the third part, but the first two parts build important foundations:

(a) Defining "skill trees" for contribution to Oppia Web and Oppia Android;

(b) Helping contributors self-assess whether they have the necessary prerequisite skills for the project, and if not, providing recommendations for how to gain those skills; and

(c) Creating tutorials for new developers to Oppia Web and Oppia Android that are specifically designed to help them "learn by example" and gain the knowledge and skills needed to tackle common tasks in both codebases.

Note that all documentation will be submitted to our GitHub wiki repository, though you might want to use tools like Google Docs to draft tutorials and get preliminary feedback on those.

We have begun drafting skill trees that you are welcome to use in your SOI. These trees are works in progress and subject to change.

How would we measure success?

• Increase in the number of new contributors who are able to successfully merge a PR for their first issue.
• Increase in the number of contributors onboarded to one of Oppia's development teams (typically after completing two starter issues).
• Increase in the number of closed "good first issues".

Knowledge/Skills needed

• Technical writing experience
• Teaching experience
• Knowledge of Python
• Knowledge of Angular
• Knowledge of Android development

• Good organizational skills
• Ability and willingness to seek feedback from the target audience, and use this feedback to improve the documentation

List of Org Admins

• Chris (@U8NWXD)

Communication

If you have questions pertaining to how-to-get-started with the various codebases, please ask them on GitHub Discussions (Web, Android). Please be specific when asking questions; this makes it easier for us to help you.

Please use the public channels above wherever possible so that others can learn from the answer to your questions. If you need to contact the org admins confidentially, you can email them at [email protected].