From 32d9e73257115f8fae298ec3f5d7c40d64a179ac Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Fri, 23 Sep 2022 13:44:06 +0530 Subject: [PATCH 1/2] Restructure landing page links #120 Reference: https://github.com/nexB/aboutcode/issues/120 Signed-off-by: Ayan Sinha Mahapatra --- docs/source/index.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 45e6fab..bf30aa1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -21,11 +21,13 @@ Table of Contents ***************** .. toctree:: - :maxdepth: 1 + :maxdepth: 2 aboutcode-project-overview - aboutcode-data/abcd contributing + archive/gsoc-toc + archive/gsod-toc + aboutcode-data/abcd doc_guidelines archive license From 43e2454e5308bc541491e9730f54b6bc84ec3a6e Mon Sep 17 00:00:00 2001 From: Ayan Sinha Mahapatra Date: Fri, 23 Sep 2022 16:24:44 +0530 Subject: [PATCH 2/2] Add GSoD 2021 Case Study Signed-off-by: Ayan Sinha Mahapatra --- docs/source/archive/gsod-toc.rst | 19 ++- .../reports/2019/scancode_toolkit_ayan.rst | 4 +- .../gsod/reports/2021/scancode_io_hanan.rst | 150 ++++++++++++++++++ docs/source/index.rst | 24 ++- 4 files changed, 190 insertions(+), 7 deletions(-) create mode 100644 docs/source/archive/gsod/reports/2021/scancode_io_hanan.rst diff --git a/docs/source/archive/gsod-toc.rst b/docs/source/archive/gsod-toc.rst index ce012ec..bf0445c 100644 --- a/docs/source/archive/gsod-toc.rst +++ b/docs/source/archive/gsod-toc.rst @@ -7,11 +7,28 @@ to contribute to open source projects.It fosters the open source contributions o GSoD was started by Google in 2019. More about of GSoD - _ +GSoD 2021 +--------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + + gsod/reports/2021/scancode_io_hanan + +GSoC 2019 +--------- + +.. toctree:: + :maxdepth: 1 gsod/reports/2019/scancode_toolkit_ayan + +GSoD project ideas pages +------------------------ + +.. toctree:: + :maxdepth: 1 + gsod/org_pages/gsod-2021 gsod/org_pages/gsod-2020 gsod/org_pages/gsod_2019 diff --git a/docs/source/archive/gsod/reports/2019/scancode_toolkit_ayan.rst b/docs/source/archive/gsod/reports/2019/scancode_toolkit_ayan.rst index 1f18975..701d616 100644 --- a/docs/source/archive/gsod/reports/2019/scancode_toolkit_ayan.rst +++ b/docs/source/archive/gsod/reports/2019/scancode_toolkit_ayan.rst @@ -1,5 +1,5 @@ -Google Season of Docs 2019 Report -================================= +scancode-toolkit Documentation GSoD Report +========================================== Project Name ------------ diff --git a/docs/source/archive/gsod/reports/2021/scancode_io_hanan.rst b/docs/source/archive/gsod/reports/2021/scancode_io_hanan.rst new file mode 100644 index 0000000..d325137 --- /dev/null +++ b/docs/source/archive/gsod/reports/2021/scancode_io_hanan.rst @@ -0,0 +1,150 @@ +scancode.io Documentation GSoD Case Study +========================================= + + +`AboutCode.org `_ is a community of open source developers who are +trying to make open source easier to use by providing open source tools to +discover, identify and track open source components (aka. Software Composition Analysis - SCA). +AboutCode is the collective name for these open source tools. + +Author: `Dennis Clark https://github.com/DennisClark` + + +Problem Statement +----------------- + +Create and update ScanCode.io HowTo Guides and Tutorials + +Proposal Abstract +----------------- + +`Project Proposal Link `_ + +Our focus for GSoD 2021 is Scancode.io and these specific tasks: + + - Create a 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 + - Upgrade the ScanCode.io Web UI documentation + - Create an introductory `video `_ to show 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. + +Project Description +------------------- + +Creating the proposal +^^^^^^^^^^^^^^^^^^^^^ + +ScanCode.io is an open platform to script and automate Software Composition Analysis (SCA) +for many different use cases including development codebases, package dependencies, and Docker, +Virtual Machine images, or other containers. With the ScanPipe feature of ScanCode.io, +you can create any number of Pipelines to integrate SCA into your development process. +A Pipeline may include libraries beyond those available from AboutCode.org. +This flexibility means that we need much more extensive HowTo, Tutorials, and Reference +documentation to help our users build their own Pipelines. ScanCode.io also offers a Web UI +that needs a new Tutorial and HowTo documentation. + +Although we already offer a few Pipeline templates, our users need to be self-sufficient +to adapt these templates or add new Pipelines in order to fit SCA into their own environment. +We also want to encourage users to contribute back improvements to our templates or new +Pipeline templates. Both of these objectives require more and better documentation. + +Budget +^^^^^^ + +Our budget for the project was $15,000 which was allocated completely to the technical +writer working on the project. + +Participants +^^^^^^^^^^^^ + +The primary participant was technical writer `Hanan Younes `_ +who responded to our announcement describing the project scope, and was the clear choice +among the many responders based on multiple criteria including clarity of vision and the +ability to execute the project goals. + +The primary mentor is a regular contributor to AboutCode.org projects and the +primary maintainer of ScanCode.io: + +- `Thomas Druez `_ + +Additional mentoring was provided by: + +- `Philippe Ombredanne `_ +- `Michael Herzog `_ +- `Dennis Clark `_ +- `Ayan Sinha Mahapatra `_ + +As an exceptionally thoughtful and articulate analyst, Hanan Younes offered much useful +feedback and many questions that encouraged the project mentors to improve their +planning and organization. We learned how valuable a clear roadmap and directions can be +to a technical writer. + +Timeline +^^^^^^^^ + +We planned that the technical writer would work on our project ⅓ to ½ time over a period +of 5 months (May to October, 2021). +Results + +The documentation for ScanCode.io was dramatically improved. See `scancode.io RTD `_ + +The documentation is now well organized into Getting Started, Tutorial, and Reference sections, +each of which provides a wealth of information. + +Tracking +^^^^^^^^ + +We used GitHub Projects to manage and track the project. All expectations were met or exceeded. + +Analysis +^^^^^^^^ + +- Hanan executed all tasks beautifully. +- We found that we needed to dig deeper into ScanCode.io to respond to Hanan's many + questions and comments. +- The project was very successful and provided everyone with the opportunity to + grow and learn. We are very pleased with the documentation that is now available + to the open source community. + +Summary +^^^^^^^ + +- Clear organization of project documentation is essential. +- We may wish to articulate more “stretch goals” in future projects. +- Be sure to define exactly what you want to accomplish. +- Be sure to plan project communication standards, such as a Gitter channel and regularly + scheduled status meetings. + +Appendix +-------- + +We received more than twenty proposals, and are grateful to the interest shown in AboutCode.org +by the open source community. + +Process Feedback to Google +-------------------------- + +The overall process for the GSoD went well, but we faced a few issues, mostly self-inflicted +that we are listing here for reference: + +- Since we were not sure if our org would be accepted, we started late working on actual + recruitment. Recruitment ended up taking much more time than planned. This means we had + to scramble when our org was accepted to get our selected candidate on-boarded and + starting the project. +- In contrast with the GSoC project, there is no infrastructure for candidates to submit + a project proposal. It was not an issue for us, but we felt after the fact that a GSoC-like + infrastructure to funnel submissions would have been a nice addition. +- There was no clear contract or agreement in place with our selected candidate and this + led to some misunderstanding between us with regard to payments. This ended up being a + source of anxiety for our doc writer and a situation we decided to address directly. + AboutCode is sponsored by nexB which is a commercial company and nexB accepted to + make a donation to the AboutCode OpenCollective as a bridge to provide advanced + payments to our doc writer. For future participation, we will manage this process + proactively to avoid such ambiguity. +- While we have been proactively managing the process with our doc writer with weekly meetings + and continuous discussions in chat channels, we mentors collectively have not been great at + providing timely feedback to GSoD administrators about our progress which is something + that we would need to improve for the future. diff --git a/docs/source/index.rst b/docs/source/index.rst index bf30aa1..f945706 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,18 +16,34 @@ All community contributions are welcome. ---- -***************** -Table of Contents -***************** +******** +Overview +******** .. toctree:: :maxdepth: 2 aboutcode-project-overview + +************************** +Contributing and GSoC/GSoD +************************** + +.. toctree:: + :maxdepth: 3 + contributing archive/gsoc-toc archive/gsod-toc - aboutcode-data/abcd doc_guidelines + +****** +Others +****** + +.. toctree:: + :maxdepth: 2 + + aboutcode-data/abcd archive license