Season of Docs 2021
- Timeline
- Getting started
- FAQ
- Starter projects
- Season of Docs Proposal
- How to apply?
- Project Ideas
- Other useful information
Oppia has applied to participate in the Season of Docs 2021 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!
Project discussion: Technical writers can discuss the project ideas with mentors and can ask mentors to give feedback on their draft “Statement of interest” doc. Submit your queries on oppia-sod-discuss@
Proposal submission: Technical writers are expected to submit their “Statement of interest” in a pdf format through the google form before the deadline to show their interest in the project.
Selection announcement: The admin* will announce the selected technical writers on oppia-sod-announce@ on 14th May 2021, 22:00 IST.
Admin: The organization administrators who are organizing and representative for the Season of Docs program on behalf of the organization.
If you're interested in applying to work with Oppia for Season of Docs, please follow these steps:
-
Read and follow the instructions to sign CLA and fill up the survey form carefully.
-
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.
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 (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.
Currently, each wiki page contains lots of information but it's hard to navigate the full page and find the required info. We believe that providing a "Table of content" at the top of the wiki page will help developers navigate and understand the content of the page quickly.
Steps to follow:
- Pick one/multiple "unresolved" page(s) from the tracker sheet here.
- Ask the mentor to assign you to those pages (leave a comment in the sheet).
- Audit the wiki page and create a table of content for the assigned wiki pages.
- Share the "Table of contents" on google docs with the mentor and ask for a review.
- Once the doc gets approved, work with the mentor to update the wiki page and tracker sheet.
Add a wiki page with helpful tips/guidelines for contributors which can help them have better contribution experiences. Some of the helpful points mentioned below:
- Don't be blocked
- Working with volunteers
- Good practices for asking questions
- Getting set up
- Do a self-review
- Find your own mistakes. Reviews take time.
- Do small PRs
- How to search a codebase?
- Understanding what's going on is super important. Don't make random changes.
Steps to follow:
- Ask a mentor to assign you to this task.
- Create a google doc and start writing the document.
- Ask a mentor for help if needed.
- Ask the mentor for a review.
- Work with the mentor to get approval on the doc and adding the wiki page on Github.
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.
When submitting a proposal, please use the provided SoD proposal template. You are welcome to ask mentors for reviews during the proposal preparation phase.
-
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.
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
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 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.
- A concrete, specific breakdown of the work to be done for each milestone.
- Should be 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.
Contributors are expected to fill up the form and share the final “Statement of interest (SOI)” in a pdf format before the deadline. If you fail to submit the form before the deadline then the organizations will not be able to see your SOI and therefore will not be able to accept you.
The Oppia project has a large technical community, comprising numerous open-source contributors from around the world. However, there are several development processes, principles, and practices that the team follows but which are not clearly documented anywhere. This can sometimes make it hard for newer contributors to the project to get started, since it results in their being unaware of these processes and practices, and sometimes lacking the necessary context to tackle issues successfully.
Currently, reviewers and mentors help/guide contributors with such questions. However, we do need to document these guidelines/principles in order to ensure that the project is welcoming and accessible for new contributors, and to help these developers contribute independently and effectively.
This project involves organizing the information architecture of the Oppia wiki. As part of this, several new additional short guides for Oppia developers in the form of "how-tos" will need to be written; these guides are intended to be helpful in addressing common questions asked by both new and experienced developers. The aim is to address all questions that Oppia developers regularly face in their work. This project would therefore include writing/updating documentation on the following topics:
- How-to docs:
- How to set-up the development environment in different[a] text editors/IDEs [Sublime, VScode, Atom]
- How to integrate third-party linters and register custom linters.
- How to set up the IDE to quickly run tests.
- How to set up the environment to support easy debugging.
- How to write and test an Apache Beam job
- How to write a new lint check
- How to integrate and upgrade third-party libraries
- How to write good end-to-end tests
- How to set-up the development environment in different[a] text editors/IDEs [Sublime, VScode, Atom]
- Docs that explain various structures and processes:
- How the various extension frameworks are structured
- rich_text_components
- interactions
- visualizations
- issues and actions
- schema-based editors
- object editors
- schema validations
- How Oppia’s build process works
- How Oppia compiles and uses protobuffers
- How the codebase is structured (including frontend and backend), and how to write a simple full-stack change (i.e., explain how the different pieces fit together)
- How Oppia’s storage infrastructure works and how the different entities are connected to each other:
- images
- explorations, skills, questions, topic
- feedback, suggestion
- users
- How the various extension frameworks are structured
- Technical writing experience
- Knowledge of Python
- Knowledge of Angular
- Feb 09 – Mar 26: Organizations apply
- Apr 16: Organizations are announced
- 1st May: Last date for submitting your proposal
- Apr 16 – May 17: Technical writer hiring
- Apr 16: Doc development can officially begin
- Sandeep Dubey (@DubeySandeep)
If you have questions pertaining to "how-to-get-started", please ask them on the oppia-dev@ mailing list. Please be specific when asking questions; this makes it easier for us to help you.