diff --git a/docs/source/gsod-toc.rst b/docs/source/gsod-toc.rst index 69e39816..7288de49 100644 --- a/docs/source/gsod-toc.rst +++ b/docs/source/gsod-toc.rst @@ -11,6 +11,7 @@ More about of GSoD - _ .. toctree:: :maxdepth: 2 + gsod/gsod-2021 gsod/gsod-2020 gsod/gsod_2019_report gsod/gsod_2019 diff --git a/docs/source/gsod/gsod-2021.rst b/docs/source/gsod/gsod-2021.rst new file mode 100644 index 00000000..aa47670b --- /dev/null +++ b/docs/source/gsod/gsod-2021.rst @@ -0,0 +1,233 @@ +.. _GSoD2021: + +=================================== +:index:`Google Season of Docs 2021` +=================================== + +AboutCode.org is applying to be a mentoring organization for the `Google Season of Docs (GSoD) 2021 `_. + +In the event that our proposal is accepted, we'll be looking for fellow members of the FOSS +community with technical writing skills and an interest in helping. If you're interested, keep +reading to get a sense of what we have in mind for GSoD 2021. + +---- + +.. contents:: Contents + :local: + :depth: 2 + +---- + +AboutCode Overview +------------------ + +AboutCode.org is a community of developers behind a suite of Software Composition Analysis tools +(command line tools, web-based and API servers and desktop applications) and data for +license, origin and security: + +* Where does the code come from? +* What software packages are present? +* What is its license? copyright? +* Is the code secure, maintained, well coded? +* Are there any known vulnerabilities? + +All these questions are important, and are relevant to millions of free and open source +software components available on the web for reuse. The answers are critical to ensure that +everyone can safely consume free and open source software. + + +*Join us to make it so!* + + +AboutCode Projects +~~~~~~~~~~~~~~~~~~ + +Our focus for GSoD 2021 is to improve documentation on our flagship projects: + +- `ScanCode Toolkit `_ +- `ScanCode.io `_ +- `Vulnerablecode `_ + +And specifically to create/update developement and user guides. + +See :ref:`aboutcode-project-overview` for a complete list of AboutCode projects. + + +Technology +~~~~~~~~~~ + +We use Python for programming AboutCode software. Our projects are a combination of +command line tools, libraries, and web based applications based on Django and JavaScript. + +Our command line tools are designed to run on Linux, macOS and Windows, and +our web-based applications run only on Linux. + +We write our documentation using reStructuredText with Sphinx and ReadTheDocs. + +We use git and GitHub to store our code and track tasks and issues. + + +Technical Skills Needed +----------------------- + +Incoming technical writers will need the following skills: + +- Basic understanding of reStructuredText, Sphinx and ReadTheDocs-based documentation + toolchain including git. +- Ability to understand and run programs from the command line in a terminal. +- Ability to read well-structured Python code, and to update Python docstrings. +- Ability to manage Windows and Linux based installation of our tools if need be in + virtual machines. +- Ability to write technical documentation such as Tutorials, How-To Guides, and + API References. + +We do not expect a working knowledge of our tools as this will be picked from mentors and +community guidance. An interest in FOSS licensing and software code and origin +analysis would be welcome but is not a hard requirement. + +Some of these skills could be picked up during the project with help from your mentors, for +candidates with strong writing skills. + + +About Your Project Application +------------------------------ + +Check out the `GSoD Tech Writer Guide `_ + and `Statement Template `_. + +Your statement of interest should be in the range of 1,000 words, +and should contain the following information, plus anything else that +you think is relevant: + +- Personal information, i.e. Your name and contact details. + +- A Project statement. + +- A detailed description of your project. + +- Description of your relevant skills. + +- Professional information: Description of previous work, existing solutions, + open-source projects, preferably with links. + +- Proposed Timeline + +- Proposed total budget + +- Do you plan to have any other commitments during GSoD that may affect your work? Any + vacations/holidays? Will you be available full time to work on your project? Please apply + only if this is a serious full time commitment during the GSoD time frame. + +Join the chat online or by IRC at https://gitter.im/aboutcode-org/gsod-season-of-docs. +Introduce yourself and start a discussion! + +An excellent, competitive way to demonstrate your capability would be to submit a documentation +improvement (small changes/typos are welcome but do not demonstrate your ability to write +documentation) to an AboutCode project, especially to ScanCode Toolkit, Scancode.io. + +Please select a project from the list below. + +---- + +Create and update scancode.io user and developer guides +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Create an HowTo guide for integrating third-party libraries into a ScanCode.io Pipeline. +* Add a tutorial for adding a new Pipeline with a third-party library. +* Extend the HowTo Guides to cover Software Composition Analysis workflows based on ScanCode.io. +* Upgrade the scancode.io Web UI documentation. +* Create an introductory `video `_ + to teach how the web UI is used. +* Update and improve the existing Pipe libraries reference API documentation (which is generated from code documentation "docstrings"). +* Sync the new documentation set with the code to support continuous integration with code changes. + +- **Level** + + - Intermediate + +- **Tech** + + - Command line processing in a Linux-compatible terminal window + - Python [Django] + - GitHub, reStructured Text and Sphinx + +- **URLs** + + - https://scancodeio.readthedocs.io + - https://github.com/nexB/scancode-io + - https://gitter.im/aboutcode-org/discuss + +- **Mentors** + + - https://github.com/johnmhoran + - https://github.com/mjherzog + - https://github.com/tdruez + - https://github.com/AyanSinhaMahapatra + + +Create ScanCode-Toolkit Plugin Author Guide +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The goal of this guide is to provide an end-to-end tutorial and instruction +set on how to create scancode-toolkit plugins, with concrete examples and to +generate a reference API documentation for modules, classes and functions used to +create plugins. + +Some of the specific supported activities would be: + +* Explain the Plugin Architechture used in scancode-toolkit +* Explain the types of plugins used in scancode-toolkit + (pre-installed/seperately-installed) and (post-scan, pre-scan, scanner) +* An exhaustive list of all plugins and what they do, with links to their code. +* How to create a minimal plugin adding some functionality to scancode-toolkit. +* Useful examples of different types of plugins +* Using `nexb/skeleton `_ as a template for plugins. + +Note: Filter current scancode-toolkit GitHub Issues by Label 'documentation' to see +many examples of specific areas for improvement. + +- **Level** + + - Intermediate + +- **Tech** + + - Some lightweight python programming to create example plugins and + understand how they are constructed, the mentors will help here. + - Command line processing in a Linux-compatible terminal window + - GitHub, reStructured Text and Sphinx + +- **URLs** + + - https://scancode-toolkit.readthedocs.io + - https://github.com/nexB/scancode-toolkit + - https://gitter.im/aboutcode-org/scancode + +- **Mentors** + + - https://github.com/johnmhoran + - https://github.com/majurg + - https://github.com/AyanSinhaMahapatra + + +---- + +Mentoring +--------- + +We have an established team of contributors that are willing to mentor the selected +Tech Writers, and they have extensive experience from mentoring in the open, including +a successful previous participation in Google Season of Docs 2019. We have a developed +a gentle and efficient way to mentor our contributors to success. + + +Contact Info +~~~~~~~~~~~~ + +Join the chat online or by IRC at https://gitter.im/aboutcode-org/gsod-season-of-docs. +Introduce yourself and start the discussion! + +You can also contact: + +- the primary org admin directly: @pombredanne and pombredanne@gmail.com +- the GSoD coordinator directly: jmhoran@nexb.com