BeagleBoard/GSoD/Proposal-2023

= About BeagleBoard.org =

BeagleBoard.org Foundation is a Michigan, USA-based 501(c)(3) non-profit corporation existing to provide education in and collaboration around the design and use of open-source software and hardware in embedded computing. They have been making affordable OpenSource computing devices since 2008. BeagleBoard.org also provides a forum for the owners and developers of open-source software and hardware to exchange ideas, knowledge and experience. The BeagleBoard.org community collaborates on the development of open source physical computing solutions including robotics, personal manufacturing tools like 3D printers and laser cutters, and other types of industrial and machine controls. Our contributors around the world want:


 * to contribute to an important and visible project
 * to learn something new and empowering
 * to challenge the status quo
 * to open what has not been open before, and
 * to not have the cost of the technology be out of reach.

= About the project =

BeagleBone users who require detailed documentation of our OpenSource projects come to the unified BeagleBoard docs website docs.beagleboard.org which holds technical information about all the Single Board Computers, Introductory learning material, git contribution guide, GSoC software projects documentation, and open Books to help users to learn about embedded linux concepts. This unified docs project is our recent take on improving the documentation delivery to the end users by combining our old software documentation and System Reference Manuals to one place. Currently it requires massive updates to sync in with the changes made in latest linux images and other massive software updates to our OpenSource projects. Additionally, porting/syncing GSoC projects documentation from original sources and delivering to potential users is required to appreciate the hard work students have put into their projects.

Although not a hard selection criteria, contributors are expected to have familiarity with ReStructured Text (RST), git, merge requests, GitLab, sphinx, and Linux.

= Project scope =

We are going to create user friendly documentation which is up to date with the current software updates. We have not identified any technical writers to work on this project as of now.

Unified BeagleBone Docs (docs.beagleboard.org) updates will:


 * 1) Evaluating the current documentation delivery approach and finding the right way to segregate the sections and chapters in a way that is more appealing to new users.
 * 2) Reducing redundant documentation while keeping links between different sections to provide a seamless experience in an efficient way.
 * 3) Understanding the visual gaps in the documentation, creating updated documentation to target it for beginners as well as advanced users.
 * 4) Validate and update the quick cheat sheet for git contribution and add more cheat sheets for things like Visual Studio Code keystrokes for improving productivity.
 * 5) Optimizing the visual elements to have blazing was web access and a light weight PDF.
 * 6) Take feedback from forum.beagleboard.org and the vast BeagleBoard community.
 * 7) Work with software developers to update the documentation and to create seamless processes to keep the docs in sync with the tools going forward.

Work that is out-of-scope for this project:



We need 3 motivated technical writing candidates for this project, and we estimate that this work will take around 6 months to complete. Deepak Khatri (lorforlinux), Jason (jkridner), and Robert (rcnee) from BeagleBoard.org are committed to support the project.

= Measuring the project’s success =

As this is something new, we don’t have many contributors and with GSoD we are hoping to expand its reach to more people who will contribute to the project. We believe that improved documentation will result in new users joining the contributors list. Since most of the contributors will start by doing basic setup of their BeagleBone hardware, their feedback will be huge to improve the documentation.


 * 1) We are planning to track the progress of the project by tracking.
 * 2) How much redundant content is removed.
 * 3) Visual aspects optimization to speed up site load times.
 * 4) Optimization of PDF to have a light yet informative file.
 * 5) Section linking and indexing to simplify updates and syncs.

We will consider the project successful if, after the publication of new documentation:
 * 1) PDF size is reduced by at least 20%
 * 2) Redundancy in content is entirely removed

= Timeline =

The project itself will take around 6 months to complete. Once the tech writer is hired, we’ll spend a month on tech writer orientation and setup. Then we will move to optimizations and finding best documentation delivery methods. The last few months will be focusing on creating the documentation and merging pull requests.

=Project budget=

As our project is a unified documentation project that includes documentation for all of our OpenSource Single Board Computers (SBC), Software, Kits, Tutorials, and Books we are going to need atleast 3 technical writers. During the actual documentation period technical writers may need volunteers and we estimated 4 volunteers for the completion of our project. To support all of the technical writers and volunteers we have estimated the budgest as shown below.

=Additional information=


 * 1) Previous experience with technical writers or documentation: Jason and Robert mentored contributors before to launch the initial release of [docs.beagleboard.org docs.beagleboard.org] which you see now. There is a mandatory weekly meeting with all technical writers and they have to send bi-weekly reports to BeagleBoard.org members over email for assessment of the submitted work. One year of mentoring for the unified docs project has provided him enough experience to handle all the technical writers during GSoD 2023.


 * 1) Previous participation in Google Season of Docs, Google Summer of Code or others: Although this will be our first GSoD participation BeagleBoard.org has been participating in GSoC for a long time and we get very useful software project submissions from students each year enabling users to fully leverage the capabilities of our OpenSource computing devices (single board computers). Also, Deepak Khatri who will be mentoring the Google Season of Docs students also did his GSoC’2020 with BeagleBoard.org and has been with BeagleBoard.org since then.