Difference between revisions of "Google Season of Docs 2019"
Jump to navigation
Jump to search
(Created page with "'''TODO WORK IN PROGRESS''' 1024px == General information == This page is the central point of information for Software Heritage participation int...") |
(→Contact: freenode -> libera) |
||
| (22 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | + | [[File:GSoDLogo.png|512px]] | |
| − | |||
| − | [[File: | ||
== General information == | == General information == | ||
| − | This page is the central point of information for [[Software Heritage]] participation into the [https:// | + | This page is the central point of information for [[Software Heritage]] participation into the [https://developers.google.com/season-of-docs/ Google Season of Docs] program. |
| − | Google | + | Google Season of Docs is a program where Google pays technical writers stipends to work on free software projects such as Software Heritage. Each writer works with mentors from the community to complete a documentation project. |
| − | == I want to participate as a | + | == I want to participate as a technical writer == |
Great!, we are very glad for your interest in contributing to Software Heritage and we are looking forward to work together. | Great!, we are very glad for your interest in contributing to Software Heritage and we are looking forward to work together. | ||
| Line 15: | Line 13: | ||
=== Prerequisites === | === Prerequisites === | ||
| − | The following prerequisites apply to Software Heritage | + | The following prerequisites apply to Software Heritage GSoD projects: |
| − | * [ | + | * [http://www.sphinx-doc.org/ Sphinx] is our documentation system of choice, you should be familiar with it to apply. In particular, we generally use reStructuredText markup and (for API references) Python docstrings with the [https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html Napoleon style] |
* [https://git-scm.com Git] is our version control system of choice, you should be familiar with it to apply | * [https://git-scm.com Git] is our version control system of choice, you should be familiar with it to apply | ||
* additional prerequisites depend on the project you will work on; check project descriptions for details | * additional prerequisites depend on the project you will work on; check project descriptions for details | ||
| Line 23: | Line 21: | ||
=== Before you apply === | === Before you apply === | ||
| − | Here are the steps you should follow before applying, to make sure you have a | + | Here are the steps you should follow before applying, to make sure you have a general idea of the current state of Software Heritage technical documentation: |
| − | + | * Learn about our project via our [https://www.softwareheritage.org/ main website] and the actual [https://archive.softwareheritage.org/ source code archive] | |
| − | + | * Check out the index of our [https://www.softwareheritage.org/community/developers/ resources for developers] | |
| − | + | * In particular make sure to have a look at: | |
| − | + | ** our [https://wiki.softwareheritage.org/ public wiki] | |
| + | ** our [https://docs.softwareheritage.org/devel/ documentation index] | ||
| + | * Technical setup: | ||
| + | ** Create an account on our [https://forge.softwareheritage.org development forge] | ||
| + | ** Familiarize yourself with our [[Code review in Phabricator|code review workflow]] | ||
| + | ** Make a simple change to the documentation of any one of our [https://docs.softwareheritage.org/devel/ software components] and submit it as a [https://forge.softwareheritage.org/differential/ diff] for code review, following the above workflow. Feel free to submit any patch you think it might be useful. | ||
=== What to include in your application === | === What to include in your application === | ||
| Line 34: | Line 37: | ||
Make sure that your application includes the following information: | Make sure that your application includes the following information: | ||
| − | * Describe the '''specific project''' you want to work on. What do you want to achieve? Why is it important? Why is it useful for Software Heritage? The project might be one of the project ideas that we have prepared below, or something else entirely that you want to contribute to Software Heritage. Your | + | * Describe the '''specific project''' you want to work on. What do you want to achieve? Why is it important? Why is it useful for Software Heritage? The project might be one of the project ideas that we have prepared below, or something else entirely that you want to contribute to Software Heritage. Your pet peeve, surprise us! |
* Detail your '''work plan''': a brief description of how you plan to go about your project, including a list of ''deliverables'' and a ''timeline'' of when do you expect them to be available. | * Detail your '''work plan''': a brief description of how you plan to go about your project, including a list of ''deliverables'' and a ''timeline'' of when do you expect them to be available. | ||
* Include a reference to '''the diff''' you submitted before applying (see the "Before you apply" section above). | * Include a reference to '''the diff''' you submitted before applying (see the "Before you apply" section above). | ||
| Line 41: | Line 44: | ||
Below you can find a list of project ideas that are good options for a | Below you can find a list of project ideas that are good options for a | ||
| − | reasonably sized | + | reasonably sized GSoD project. They are just suggestion though, don't feel |
obliged to pick one of them if there is nothing that fits your taste and | obliged to pick one of them if there is nothing that fits your taste and | ||
abilities. Feel free to propose something else that you are excited about and | abilities. Feel free to propose something else that you are excited about and | ||
| − | that contributes to improve the Software Heritage | + | that contributes to improve the Software Heritage documentation: we will be |
| − | consider it! | + | happy to consider it! |
| − | === | + | === Reorganize developer documentation as tutorials/how-to/discussions/references === |
| − | + | Our [https://docs.softwareheritage.org/devel/ developer documentation] is not particularly structured, making it hard to use it properly. | |
| − | + | We would like to reorganize it following the [https://www.youtube.com/watch?v=t4vKPhjcMZg tutorials/how-to/discussions/references taxonomy], or something equally sensible. | |
| − | |||
| − | + | This project will require discussing the intended use cases of this page, conceptually structure the future version of it, implement it, and (re)write suitable language to introduce the various parts. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | === Write a high-level technical overview of the project, data model, and data flow === | |
| − | + | We have described the data model and archival data flow of Software Heritage in [https://upsilon.cc/~zack/research/publications/ipres-2018-doi.pdf various] [https://upsilon.cc/~zack/research/publications/cacm-2018-software-heritage.pdf scientific] [https://upsilon.cc/~zack/research/publications/msr-2019-swh.pdf papers], but haven't really worked on a general, high-level, technical presentation of it that targets developers. | |
| − | to | + | The current [https://docs.softwareheritage.org/devel/swh-model/data-model.html#data-model data model documentation] has been copy-pasted from scientific papers. |
| + | We want to revisit it, to make sure the language description is suitable for a more general technical public, possibly complementing it with more abstract data-structure descriptions and cross-references to the code implementing the model and the workflow in the actual implementation. | ||
| − | + | === Design and document consistent writing conventions for Python docstrings === | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | The docstrings of the [https://docs.softwareheritage.org/devel/#components various software components] in the Software Heritage stack are not very consistent. | |
| − | + | They have been written by a number of different developers, with varying degrees of English proficiency. | |
| − | |||
| − | [https://docs.softwareheritage.org/devel/ | ||
| − | + | We would like to document, as a set of writing guidelines, how to write them to the benefits of current and future developers. | |
| − | + | The guidelines should include what to write in docstrings and whatnot, writing styles and guidance, examples of good and bad content for them, etc. | |
| − | |||
| − | + | To the extent it is possible, this project will also explore automating checks for guidelines conformance, in the form of basic structural (e.g., are all function parameters documented? is the function name correct? etc.) and writing checks (e.g., spellchecking, grammar checking, etc.). | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | === | + | === Revamp new (code) contributor tutorial === |
| − | + | The current [https://docs.softwareheritage.org/devel/#getting-started getting started documentation] include two overlapping documents: one about how to ''run'' a local instance of the full Software Heritage stack, another about how to create a local setup for current and future project ''developers''. | |
| − | + | We would like to review those documents for consistency and, more generally, revamp documentation that will help wannabe code contributors to quickly get started and submit patches. | |
| − | + | As part of this project we might also want to revamp glossary, data model and other cross-cutting documents that help newcomers understand where-is-what in the code base and how to practically prepare and send us patches. | |
| − | |||
| − | |||
| − | |||
| − | + | === Restructure wiki landing page as main community entry point === | |
| − | |||
| − | + | Our [[Main_Page|public wiki landing page]] is, well, a mess. | |
| − | + | It has grown inorganically by accumulating links to pages used more as working drafts than reasonably structured documents. | |
| − | + | We would like to restructure it to cater for various use cases (users, developers, students, curators, scientists, etc.) in the attempt of making it the primary entry point into Software Heritage for all community members. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | This project will require discussing the various uses cases, design a suitable page layout, implement it in the wiki, write the introductory parts for each path into the wiki. | |
| − | + | A related task, if time permits, will be to reorganize the wiki [[Special:Categories|category taxonomy]] and document when/how to use the available categories in the future. | |
| − | + | Working on this project will require familiarity with [https://www.mediawiki.org/wiki/MediaWiki Mediawiki] and its markup language. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== Contact == | == Contact == | ||
| − | + | GSoD applicants are encouraged to get in touch with the Software Heritage community using the standard development communication channels, i.e.: | |
| − | * the #swh-devel IRC channel on [https:// | + | * the #swh-devel IRC channel on [https://libera.chat/ Libera Chat] |
* the [https://sympa.inria.fr/sympa/info/swh-devel swh-devel mailing list] | * the [https://sympa.inria.fr/sympa/info/swh-devel swh-devel mailing list] | ||
| Line 157: | Line 102: | ||
== Timeline == | == Timeline == | ||
| − | See the official [https://developers.google.com/ | + | See the official [https://developers.google.com/season-of-docs/docs/timeline Google Season of Docs timeline]. |
| + | |||
| + | [[Category:Google Season of Docs]] | ||
Latest revision as of 07:30, 15 June 2021
General information
This page is the central point of information for Software Heritage participation into the Google Season of Docs program.
Google Season of Docs is a program where Google pays technical writers stipends to work on free software projects such as Software Heritage. Each writer works with mentors from the community to complete a documentation project.
I want to participate as a technical writer
Great!, we are very glad for your interest in contributing to Software Heritage and we are looking forward to work together.
Prerequisites
The following prerequisites apply to Software Heritage GSoD projects:
- Sphinx is our documentation system of choice, you should be familiar with it to apply. In particular, we generally use reStructuredText markup and (for API references) Python docstrings with the Napoleon style
- Git is our version control system of choice, you should be familiar with it to apply
- additional prerequisites depend on the project you will work on; check project descriptions for details
Before you apply
Here are the steps you should follow before applying, to make sure you have a general idea of the current state of Software Heritage technical documentation:
- Learn about our project via our main website and the actual source code archive
- Check out the index of our resources for developers
- In particular make sure to have a look at:
- our public wiki
- our documentation index
- Technical setup:
- Create an account on our development forge
- Familiarize yourself with our code review workflow
- Make a simple change to the documentation of any one of our software components and submit it as a diff for code review, following the above workflow. Feel free to submit any patch you think it might be useful.
What to include in your application
Make sure that your application includes the following information:
- Describe the specific project you want to work on. What do you want to achieve? Why is it important? Why is it useful for Software Heritage? The project might be one of the project ideas that we have prepared below, or something else entirely that you want to contribute to Software Heritage. Your pet peeve, surprise us!
- Detail your work plan: a brief description of how you plan to go about your project, including a list of deliverables and a timeline of when do you expect them to be available.
- Include a reference to the diff you submitted before applying (see the "Before you apply" section above).
Ideas list
Below you can find a list of project ideas that are good options for a reasonably sized GSoD project. They are just suggestion though, don't feel obliged to pick one of them if there is nothing that fits your taste and abilities. Feel free to propose something else that you are excited about and that contributes to improve the Software Heritage documentation: we will be happy to consider it!
Reorganize developer documentation as tutorials/how-to/discussions/references
Our developer documentation is not particularly structured, making it hard to use it properly. We would like to reorganize it following the tutorials/how-to/discussions/references taxonomy, or something equally sensible.
This project will require discussing the intended use cases of this page, conceptually structure the future version of it, implement it, and (re)write suitable language to introduce the various parts.
Write a high-level technical overview of the project, data model, and data flow
We have described the data model and archival data flow of Software Heritage in various scientific papers, but haven't really worked on a general, high-level, technical presentation of it that targets developers. The current data model documentation has been copy-pasted from scientific papers. We want to revisit it, to make sure the language description is suitable for a more general technical public, possibly complementing it with more abstract data-structure descriptions and cross-references to the code implementing the model and the workflow in the actual implementation.
Design and document consistent writing conventions for Python docstrings
The docstrings of the various software components in the Software Heritage stack are not very consistent. They have been written by a number of different developers, with varying degrees of English proficiency.
We would like to document, as a set of writing guidelines, how to write them to the benefits of current and future developers. The guidelines should include what to write in docstrings and whatnot, writing styles and guidance, examples of good and bad content for them, etc.
To the extent it is possible, this project will also explore automating checks for guidelines conformance, in the form of basic structural (e.g., are all function parameters documented? is the function name correct? etc.) and writing checks (e.g., spellchecking, grammar checking, etc.).
Revamp new (code) contributor tutorial
The current getting started documentation include two overlapping documents: one about how to run a local instance of the full Software Heritage stack, another about how to create a local setup for current and future project developers. We would like to review those documents for consistency and, more generally, revamp documentation that will help wannabe code contributors to quickly get started and submit patches.
As part of this project we might also want to revamp glossary, data model and other cross-cutting documents that help newcomers understand where-is-what in the code base and how to practically prepare and send us patches.
Restructure wiki landing page as main community entry point
Our public wiki landing page is, well, a mess. It has grown inorganically by accumulating links to pages used more as working drafts than reasonably structured documents. We would like to restructure it to cater for various use cases (users, developers, students, curators, scientists, etc.) in the attempt of making it the primary entry point into Software Heritage for all community members.
This project will require discussing the various uses cases, design a suitable page layout, implement it in the wiki, write the introductory parts for each path into the wiki. A related task, if time permits, will be to reorganize the wiki category taxonomy and document when/how to use the available categories in the future.
Working on this project will require familiarity with Mediawiki and its markup language.
Contact
GSoD applicants are encouraged to get in touch with the Software Heritage community using the standard development communication channels, i.e.:
- the #swh-devel IRC channel on Libera Chat
- the swh-devel mailing list
See our development information page for more details.
Timeline
See the official Google Season of Docs timeline.