|
| 1 | +scancode.io Documentation GSoD Case Study |
| 2 | +========================================= |
| 3 | + |
| 4 | + |
| 5 | +`AboutCode.org <https://www.aboutcode.org/>`_ is a community of open source developers who are |
| 6 | +trying to make open source easier to use by providing open source tools to |
| 7 | +discover, identify and track open source components (aka. Software Composition Analysis - SCA). |
| 8 | +AboutCode is the collective name for these open source tools. |
| 9 | + |
| 10 | +Author: `Dennis Clark https://github.com/DennisClark` |
| 11 | + |
| 12 | + |
| 13 | +Problem Statement |
| 14 | +----------------- |
| 15 | + |
| 16 | +Create and update ScanCode.io HowTo Guides and Tutorials |
| 17 | + |
| 18 | +Proposal Abstract |
| 19 | +----------------- |
| 20 | + |
| 21 | +`Project Proposal Link <https://www.google.com/url?q=https://docs.google.com/document/d/1jW2ogyALIBNsVpHhQ0EbBKzpfPF8BJzmT4vCfU3sQso/edit&>`_ |
| 22 | + |
| 23 | +Our focus for GSoD 2021 is Scancode.io and these specific tasks: |
| 24 | + |
| 25 | + - Create a HowTo guide for integrating third-party libraries into a ScanCode.io Pipeline. |
| 26 | + - Add a tutorial for adding a new Pipeline with a third-party library. |
| 27 | + - Extend the HowTo Guides to cover Software Composition Analysis workflows |
| 28 | + - Upgrade the ScanCode.io Web UI documentation |
| 29 | + - Create an introductory `video <https://opensource.com/article/21/3/video-open-source-tools>`_ to show how the web UI is used. |
| 30 | + - Update and improve the existing Pipe libraries reference API documentation |
| 31 | + (which is generated from code documentation "docstrings"). |
| 32 | + - Sync the new documentation set with the code to support continuous integration. |
| 33 | + |
| 34 | +Project Description |
| 35 | +------------------- |
| 36 | + |
| 37 | +Creating the proposal |
| 38 | +^^^^^^^^^^^^^^^^^^^^^ |
| 39 | + |
| 40 | +ScanCode.io is an open platform to script and automate Software Composition Analysis (SCA) |
| 41 | +for many different use cases including development codebases, package dependencies, and Docker, |
| 42 | +Virtual Machine images, or other containers. With the ScanPipe feature of ScanCode.io, |
| 43 | +you can create any number of Pipelines to integrate SCA into your development process. |
| 44 | +A Pipeline may include libraries beyond those available from AboutCode.org. |
| 45 | +This flexibility means that we need much more extensive HowTo, Tutorials, and Reference |
| 46 | +documentation to help our users build their own Pipelines. ScanCode.io also offers a Web UI |
| 47 | +that needs a new Tutorial and HowTo documentation. |
| 48 | + |
| 49 | +Although we already offer a few Pipeline templates, our users need to be self-sufficient |
| 50 | +to adapt these templates or add new Pipelines in order to fit SCA into their own environment. |
| 51 | +We also want to encourage users to contribute back improvements to our templates or new |
| 52 | +Pipeline templates. Both of these objectives require more and better documentation. |
| 53 | + |
| 54 | +Budget |
| 55 | +^^^^^^ |
| 56 | + |
| 57 | +Our budget for the project was $15,000 which was allocated completely to the technical |
| 58 | +writer working on the project. |
| 59 | + |
| 60 | +Participants |
| 61 | +^^^^^^^^^^^^ |
| 62 | + |
| 63 | +The primary participant was technical writer `Hanan Younes <https://github.com/hyounes4560>`_ |
| 64 | +who responded to our announcement describing the project scope, and was the clear choice |
| 65 | +among the many responders based on multiple criteria including clarity of vision and the |
| 66 | +ability to execute the project goals. |
| 67 | + |
| 68 | +The primary mentor is a regular contributor to AboutCode.org projects and the |
| 69 | +primary maintainer of ScanCode.io: |
| 70 | + |
| 71 | +- `Thomas Druez <https://github.com/tdruez>`_ |
| 72 | + |
| 73 | +Additional mentoring was provided by: |
| 74 | + |
| 75 | +- `Philippe Ombredanne <https://github.com/pombredanne>`_ |
| 76 | +- `Michael Herzog <https://github.com/mjherzog>`_ |
| 77 | +- `Dennis Clark <https://github.com/DennisClark>`_ |
| 78 | +- `Ayan Sinha Mahapatra <https://github.com/AyanSinhaMahapatra>`_ |
| 79 | + |
| 80 | +As an exceptionally thoughtful and articulate analyst, Hanan Younes offered much useful |
| 81 | +feedback and many questions that encouraged the project mentors to improve their |
| 82 | +planning and organization. We learned how valuable a clear roadmap and directions can be |
| 83 | +to a technical writer. |
| 84 | + |
| 85 | +Timeline |
| 86 | +^^^^^^^^ |
| 87 | + |
| 88 | +We planned that the technical writer would work on our project ⅓ to ½ time over a period |
| 89 | +of 5 months (May to October, 2021). |
| 90 | +Results |
| 91 | + |
| 92 | +The documentation for ScanCode.io was dramatically improved. See `scancode.io RTD <https://scancodeio.readthedocs.io>`_ |
| 93 | + |
| 94 | +The documentation is now well organized into Getting Started, Tutorial, and Reference sections, |
| 95 | +each of which provides a wealth of information. |
| 96 | + |
| 97 | +Tracking |
| 98 | +^^^^^^^^ |
| 99 | + |
| 100 | +We used GitHub Projects to manage and track the project. All expectations were met or exceeded. |
| 101 | + |
| 102 | +Analysis |
| 103 | +^^^^^^^^ |
| 104 | + |
| 105 | +- Hanan executed all tasks beautifully. |
| 106 | +- We found that we needed to dig deeper into ScanCode.io to respond to Hanan's many |
| 107 | + questions and comments. |
| 108 | +- The project was very successful and provided everyone with the opportunity to |
| 109 | + grow and learn. We are very pleased with the documentation that is now available |
| 110 | + to the open source community. |
| 111 | + |
| 112 | +Summary |
| 113 | +^^^^^^^ |
| 114 | + |
| 115 | +- Clear organization of project documentation is essential. |
| 116 | +- We may wish to articulate more “stretch goals” in future projects. |
| 117 | +- Be sure to define exactly what you want to accomplish. |
| 118 | +- Be sure to plan project communication standards, such as a Gitter channel and regularly |
| 119 | + scheduled status meetings. |
| 120 | + |
| 121 | +Appendix |
| 122 | +-------- |
| 123 | + |
| 124 | +We received more than twenty proposals, and are grateful to the interest shown in AboutCode.org |
| 125 | +by the open source community. |
| 126 | + |
| 127 | +Process Feedback to Google |
| 128 | +-------------------------- |
| 129 | + |
| 130 | +The overall process for the GSoD went well, but we faced a few issues, mostly self-inflicted |
| 131 | +that we are listing here for reference: |
| 132 | + |
| 133 | +- Since we were not sure if our org would be accepted, we started late working on actual |
| 134 | + recruitment. Recruitment ended up taking much more time than planned. This means we had |
| 135 | + to scramble when our org was accepted to get our selected candidate on-boarded and |
| 136 | + starting the project. |
| 137 | +- In contrast with the GSoC project, there is no infrastructure for candidates to submit |
| 138 | + a project proposal. It was not an issue for us, but we felt after the fact that a GSoC-like |
| 139 | + infrastructure to funnel submissions would have been a nice addition. |
| 140 | +- There was no clear contract or agreement in place with our selected candidate and this |
| 141 | + led to some misunderstanding between us with regard to payments. This ended up being a |
| 142 | + source of anxiety for our doc writer and a situation we decided to address directly. |
| 143 | + AboutCode is sponsored by nexB which is a commercial company and nexB accepted to |
| 144 | + make a donation to the AboutCode OpenCollective as a bridge to provide advanced |
| 145 | + payments to our doc writer. For future participation, we will manage this process |
| 146 | + proactively to avoid such ambiguity. |
| 147 | +- While we have been proactively managing the process with our doc writer with weekly meetings |
| 148 | + and continuous discussions in chat channels, we mentors collectively have not been great at |
| 149 | + providing timely feedback to GSoD administrators about our progress which is something |
| 150 | + that we would need to improve for the future. |
0 commit comments