Season of Docs 2019

Table of Contents

• Getting started
• FAQ
• Starter projects
• Season of Docs Proposal
  • Template
  • Tips for writing a good project plan
  • Selection criteria
• Project Ideas
• Other useful information
  • Dates and Deadlines
  • List of Mentors
  • Communication

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:

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

2. 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.

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

Email

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.