# Season of docs 2019 ## Table of Contents * [Getting started](#getting-started) * [FAQ](#faq) * [Starter projects](#starter-projects) * [Season of Docs Proposal](#season-of-docs-proposal) * [Template](#template) * [Tips for writing a good project plan](#tips-for-writing-a-good-project-plan) * [Selection criteria](#selection-criteria) * [Project Ideas](#project-ideas) * [Other useful information](#other-useful-information) * [Dates and Deadlines](#dates-and-deadlines) * [List of Mentors](#list-of-potential-mentors) * [Communication](#communication) Oppia is planning to participate in the first year of the [Season of Docs](https://developers.google.com/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](https://github.com/oppia/oppia/wiki). 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@](https://groups.google.com/forum/#!forum/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@](https://groups.google.com/forum/#!forum/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! 1. Get a better understanding of what Oppia is all about by taking a look at our [user documentation](http://oppia.github.io/#/) — 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](https://www.oppia.org), like [these ones on Fractions](https://www.oppia.org/fractions), to get a better idea of what they look like. 1. 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](mailto:oppia-sod-discuss@googlegroups.com). 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](#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](https://github.com/oppia/oppia/wiki) and [User documentation](http://oppia.github.io/#/)), 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@](https://groups.google.com/forum/#!forum/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](http://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](https://github.com/oppia/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](https://github.com/oppia/oppia/wiki), 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](https://github.com/oppia/oppia/wiki/Overview-of-the-Oppia-codebase)) * 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](https://gitter.im/oppia/oppia-chat)! 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]( https://gitter.im/oppia/oppia-chat), or the oppia-dev@ mailing list. Please be specific when asking questions; this makes it easier for us to help you.