Skip to content

GSoD 2023

Jump to bottom
Michael Herzog edited this page Mar 23, 2023 · 6 revisions

AboutCode will be applying as a Google Season of Docs (GSoD) mentoring organization for 2023! See https://developers.google.com/season-of-docs/ for more details about the program this year. Here is the complete timeline: https://developers.google.com/season-of-docs/docs/timeline

TL;DR See our list of ideas: https://github.com/nexB/aboutcode/wiki/GSOD-2023#our-project-ideas

Please also review our tech writer selection process.

We are looking for fellow members of the FOSS community with technical writing skills and an interest in our organization. If you’re interested, keep reading to get a sense of what we have in mind for GSoD 2023.

Note: This page is still Work In Progress, we will be adding more project ideas and other guidelines on this page in so keep an eye out!

Table of Contents

About Us:

AboutCode is a community of FOSS projects to uncover data ... about software code:

  • where does the code come from? which software package?
  • what is its license? copyright?
  • is the code vulnerable, maintained, well coded?
  • what are its dependencies, are there vulnerabilities or licensing issues?

All these are questions that are important to answer: there are millions of free and open source software components available on the web for reuse. This domain is often called Software Composition Analysis or SCA.

Knowing where a software package comes from, what its license is and whether it is vulnerable is necessary so that everyone can safely use and contribute to more free and open source software. We support not only open source software, but also open data, generated and curated with our applications.

Join us to make it so!

Our tools are used to help detect and report the origin and license of source code, packages and binaries as well as discover software and package dependencies, and track security vulnerabilities, bugs and other important software package attributes. They also support creating SBOMs and other disclosure documents with this information with support for leading standards like SPDX, CycloneDX and VEX. They are a suite of database backed Web/API servers, command line applications and desktop applications. You can use our tools together or separately to create and provide data about software usability and health.

AboutCode projects are...

NOTE: If you are looking for the Project Ideas List instead of their parent Projects, see https://github.com/nexB/aboutcode/wiki/GSOD-2023#our-project-ideas

AboutCode project repositories which are the main focus of GSoD 2023 are:

  • PurlDB consists of tools to create and expose a database of purls (Package URLs) and their associate metadata. These are designed to be used first for reference such that one can query for packages by purl and validate purl existence.

  • VulnerableCode is a web-based API and database to collect and track all the known software package vulnerabilities, with affected and fixed packages, references and a standalone tool Vulntotal to compare this vulneribility information across similar tools.

Another area of focus is data attributes which are common across AboutCode projects.

Some other AboutCode project repositories are:

Contact

Join the chat online at app.gitter.im or if you're using the element app set the homeserver to gitter.im and then join the aboutcode-org/gsod-season-of-docs chatroom. Introduce yourself and start the discussion!

Please try asking questions the smart way: http://www.catb.org/~esr/faqs/smart-questions.html

For personal issues, you can contact the primary org admin directly: @pombredanne and [email protected]

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

Skills

Incoming technical writers will need the following skills:

  • Basic understanding of a documentation toolchain based on reStructuredText, Sphinx, ReadTheDocs and Git.
  • Ability to understand and run programs from the command line in a terminal session.
  • 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.
  • Ability to understand and navigate basic Python/Django code is a plus.

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, supply-chain vulnerabilities and software code and origin analysis would be welcome but is not a hard requirement.

Some of these skills could be developed 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 Creating a Statement of Interest.

See also our statement of interest guide.

Your statement of interest should be to the point, and should contain the following information, plus anything else that you think is relevant:

  • Personal information, i.e. Your name, contact details and GitHub username.
  • A Project statement.
  • A detailed description of your project proposal.
  • Description of your relevant skills.
  • Your prior experience on writing technical documentation (with openly available links):
    • Do you have experience writing documentation for specific projects/products?
    • Do you have experience writing user-facing or developer-facing documentation on projects/products?
    • Do you have blogs on technical topics?
    • Do you have articles on technical, educational topics?
    • Have you written tutorials/how-to-guides/reference docs/API documentation previously? DO you understand the differences and our requirements here?
  • Professional information: Description of previous work, existing solutions, open-source projects, preferably with links.
  • Proposed Timeline (we already specify this)
  • Proposed total budget (we already specify this)
  • 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.

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 VulnerableCode and/or ScanCode.io.

Also refer to https://github.com/nexB/aboutcode/wiki/GSoD-Technical-Writer-Selection-Process to learn more about our selection process.

Our Project ideas

These are the main areas that we think would benefit from better documentation, but keep in mind that we will be selecting only one project from these, and the final project could contain elements from multiple documentation projects listed here.

Add reference documentation and getting started guides for PurlDB.

Tasks

  • Add reference documentation on why use PurlDB?
  • Add reference documentation on PurlDB and it's components
    • packagedb
    • matchcode
    • minecode
  • Add reference documentation for how PurlDB works, such as:
    • what is matching and mining for packages
    • how this is used to create a database of packages
  • Update local development installation and configuration documentation
  • Update running visitors/mappers usage guidelines
  • Enhance the docs in https://github.com/nexB/purldb#readme into RTD pages and sections

URLs

Mentors

Add reference documentation for VulnerableCode

Tasks

  • Add reference documentation on why use VulnerableCode? explaining the following:
    • problems in vulnerability data
    • our vision in starting VulnerableCode
    • our solution in more details
  • Add reference documentation on improvers and how we have safeguards against bad data
  • Add reference documentation about univers and version ranges supported
  • Add reference documentation on our data models and output data (vulnerability and package models)

URLs

Mentors

Add new How-To guides and Tutorials for VulnerableCode

Tasks

  • Create a tutorial on using the new VulnerableCode UI to look for vulnerabilities or vulnerable packages
  • Create a how-to guide on setting up a local development installation of VulnerableCode with released data dumps
  • Update contribution tutorials on adding new importers/improvers

URLs

Mentors

Add reference documentation for AboutCode Data (ABCD) structures

Tasks

  • Add common documentation for data models common across all AboutCode projects
    • example: package models are similar and share attributes across these projects: ScanCode-Toolkit, ScanCode.io, PurlDB, package-inspectors and more.
  • Document all attributes of these data models in a structured format (like JSON)
  • Build RTD documentation from this data
  • Add relationship diagrams to help understand the data models and data attributes
  • Bonus: also prototype importing this as documentation/explanation of data attributes for all projects

URLs

Mentors

Add a glossary of concepts/words used in AboutCode projects

Tasks

  • compile a complete list of words/concepts used in AboutCode projects and what the implied meanings are. Some of these are:
    • different flavors of packages: top-level packages, package_data, resolved_package, dependency
    • around vulnerabilities, packages and their relationships
  • add detailed explanations and reference documentation for these

URLs

Mentors

http://aboutcode.org/

Clone this wiki locally