Google Season of Docs 2019
AboutCode has been accepted as a participant in the Google Season of Documents in 2019 as a mentoring org, and is looking for people with technical writing skills. This page contains information for technical writers and anyone else interested in helping.
AboutCode is a family 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 secure, maintained, well coded?
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!
Our tools are used to help detect and report the origin and license of source code, packages and binaries as well as to discover software and package dependencies, and in the future track security vulnerabilities, bugs and other important software package attributes. This is a suite of command line tools, web-based and API servers and desktop applications.
Table of Contents
List of AboutCode projects
Note that the AboutCode focus for GSOD 2019 is on ScanCode Toolkit and ScanCode Workbench, although proposals to improve the documents of other AboutCode projects are welcome.
ScanCode Toolkit is a popular command line tool to scan code for licenses, copyrights and packages, used by many organizations and FOSS projects, small and large.
Scancode Workbench (formerly AboutCode Manager) is a JavaScript, Electron-based desktop application to review scan results and document your origin and license conclusions.
Other AboutCode projects are described at https://www.aboutcode.org and https://github.com/nexB/aboutcode
We also work closely with, contribute to and have co-started several other orgs and projects:
Package URL is an emerging standard to reference software packages of all types with simple, readable and concise URLs.
SPDX is the Software Package Data Exchange, a specification to document the origin and licensing of software packages.
ClearlyDefined is a project to review FOSS software and help FOSS projects to improve their licensing and documentation clarity.
Contact
Join the chat online or by IRC at https://gitter.im/aboutcode-org/discuss Introduce yourself and start the discussion!
For personal issues, you can contact the primary org admin directly: @pombredanne and pombredanne@gmail.com
or the GSOD coordinator directly at dmclark@nexb.com
Please ask questions the smart way: http://www.catb.org/~esr/faqs/smart-questions.html
Technology
We primarily use Python (and some C/C++) for code analysis. We use Electron/JavaScript for GUI.
Our domain includes text analysis and processing (for instance for copyright and license detection), parsing (for package manifest formats), binary analysis (to detect the origin and license of binaries, which source code they come from, etc.) as well as web based tools and APIs (to expose the tools and libraries as web services) and low-level data structures for efficient matching (such as Aho-Corasick and other automata).
Our documentation is provided in text files that support the help function of our command line tools. We also have begun to provide documentation in the Wiki section of some AboutCode projects.
Technical Writing Skills Needed
Incoming technical writers will need the following skills:
Ability to install and configure open source code from GitHub.
Ability to understand and run programs from the command line in a terminal window.
Familiarity with the four document functions described at https://www.divio.com/blog/documentation/
Ability to create and edit wiki pages with multiple markdown languages.
An interest in FOSS licensing and software code and origin analysis.
We are happy to help you get up to speed, and the more you are able to demonstrate ability and skills in advance, the more likely we are to choose your application!
About your project application
Your application should be in the range of 1000 words, and should contain the following information, plus anything else that you think is relevant:
Your name and contact details
Title of your proposal
Abstract of your proposal
Description of your idea including an explanation of what it will contribute to the project, such as the software development life cycle requirements that you expect to help with the documentation improvements.
Description of previous work, existing solutions, open-source projects, preferably with links.
Details of your academic studies and any previous internships.
Descriptions of your relevant skills.
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/discuss Introduce yourself and start the discussion!
An excellent, competitive way to demonstrate your capability would be to submit a documentation improvement to an AboutCode project, especially to ScanCode Toolkit or ScanCode Workbench.
You can pick any project idea from the list below. You can also submit Your Documentation Project ideas.
Our Documentation Project ideas
Here is a list of candidate project ideas for your consideration, organized by documentation function: Tutorial , How-To , Reference , Discussion.
Note that the AboutCode focus for GSOD 2019 is on ScanCode Toolkit and ScanCode Workbench, although proposals to improve the documents of other AboutCode projects are welcome.
Your Documentation Project ideas are welcome too! Please chat about them to increase your chances of success!
Tutorial ideas
Scan a Codebase and Analyze the Results
Provide specific instructions to guide a new user to:
Scan a somewhat complex sample codebase using scancode-toolkit.
Import the results into ScanCode Workbench.
Analyze the scan results.
Level
Intermediate
Tech
Command line processing in a Linux-compatible terminal window
URLS
Mentors
How-To ideas
How To Get the License Clarity Score of a Package
Explain the recommended scancode-toolkit options to get a license clarity score.
Level
Intermediate
Tech
Command line processing in a Linux-compatible terminal window
URLS
Mentors
How To Discover Licensing Issues in a Software Project
Explain the recommended scancode-toolkit options to discover licenses.
Explain how to take advantage of license policy support.
Level
Intermediate
Tech
Command line processing in a Linux-compatible terminal window
URLS
Mentors
Reference ideas
ScanCode Output Formats
Explain the various ScanCode output formats and their business purposes.
Level
Intermediate
Tech
Command line processing in a Linux-compatible terminal window
URLS
Mentors
Discussion ideas
Integrating ScanCode into a Software Development Lifecycle
Discuss options and techniques to integrate ScanCode into a software development lifecycle workflow:
During software creation and maintenance.
During software check-out/check-in.
During sofware build and test.
Level
Intermediate
Tech
Command line processing in a Linux-compatible terminal window
URLS
Mentors
Your Documentation Project ideas
Download and install ScanCode Toolkit and ScanCode Workbench and try them out. For example, you may try scanning an open source software package in a technology with which you are familiar. What are the documentation weak points?
Is it difficult to get started? A Tutorial document opportunity.
Is it difficult to accomplish a specific objective? A How-To document opportunity.
Are the capabilities of the tool too mysterious? Do you want to know more about what you can do with it? A Reference document opportunity.
Do you feel that you need to understand its concepts better in order to use it and trust it? Do you want to know more about how the code scanning actually works? A Discussion document opportunity.
Feel free to propose and describe your own documentation ideas.
Mentoring
We welcome new mentors to help with the program. We require some understanding of the project domain to join as a mentor. Contact the team on Gitter at https://gitter.im/aboutcode-org/discuss