Difference between revisions of "BeagleBoard/GSoD/Proposal-2023"
Lorforlinux (talk | contribs) |
Lorforlinux (talk | contribs) |
||
(3 intermediate revisions by the same user not shown) | |||
Line 126: | Line 126: | ||
=Additional information= | =Additional information= | ||
− | # '''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 | + | # '''Previous experience with technical writers or documentation:''' Jason and Robert mentored contributors before to launch the initial release of [https://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 them enough experience to handle all the technical writers during GSoD 2023. |
# '''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 [https://summerofcode.withgoogle.com/archive/2020/projects/6248850903269376 GSoC’2020 with BeagleBoard.org] and has been with BeagleBoard.org since then. | # '''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 [https://summerofcode.withgoogle.com/archive/2020/projects/6248850903269376 GSoC’2020 with BeagleBoard.org] and has been with BeagleBoard.org since then. |
Latest revision as of 12:36, 24 March 2023
Contents
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:
- 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.
- Reducing redundant documentation while keeping links between different sections to provide a seamless experience in an efficient way.
- Understanding the visual gaps in the documentation, creating updated documentation to target it for beginners as well as advanced users.
- 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.
- Optimizing the visual elements to have blazing was web access and a light weight PDF.
- Take feedback from forum.beagleboard.org and the vast BeagleBoard community.
- 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.
- We are planning to track the progress of the project by tracking.
- How much redundant content is removed.
- Visual aspects optimization to speed up site load times.
- Optimization of PDF to have a light yet informative file.
- Section linking and indexing to simplify updates and syncs.
We will consider the project successful if, after the publication of new documentation:
- PDF size is reduced by at least 20%
- 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.
11th May - 8th June | Orientation | Community Bonding Period and discussion on the project and resources available. |
12th June | Milestone #0 | Introductory youtube video. |
June 14, 2023 - June 21, 2023 at 18:00 UTC | Evaluation #1 | First monthly evaluation period |
June 26th | Milestone #1 | First bi-weekly report |
July 10th | Milestone #2 | Second bi-weekly report |
July 14, 2023 - July 21, 2023 at 18:00 UTC | Evaluation #2 | Second monthly evaluation period. |
July 24th | Milestone #3 | Third bi-weekly report |
August 7th | Milestone #4 | Fourth bi-weekly report |
August 14, 2023 - August 21, 2023 at 18:00 UTC | Evaluation #3 | Third monthly evaluation period |
August 21st | Milestone #5 | Fifth bi-weekly report |
September 4th | Milestone #6 | Sixth bi-weekly report |
September 18th | Milestone #7 | Seventh bi-weekly report |
September 14, 2023 - September 21, 2023 at 18:00 UTC | Evaluation #4 | Fourth monthly evaluation period |
October 2nd | Milestone #8 | Eighth bi-weekly report |
October 16th | Milestone #9 | Ninth bi-weekly report |
October 16, 2023 - October 23, 2023 at 18:00 UTC | Evaluation #5 | Fifth and final monthly evaluation period |
October 30th | Milestone #10 | Tenth bi-weekly report |
November 13th | Farewell | Final YouTube video release and online meetup |
November 6, 2023 - November 21, 2023 at 18:00 UTC | Project wrap-up | Organization administrators submit their case study and final project evaluation |
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.
Budget item | Amount | Running total | Notes/justifications |
Technical writers | $3000 | $9000 | Three technical writers ($500/month (for 6 months) x 3) |
Volunteer stipends | $500 | $2000 | Four volunteers in total |
Project t-shirts, stickers and goodies (swag bag) | $30 | $180 | Total six goodies bags |
BeagleBone boards and capes | $700 | If required six BeagleBoard hardware kits we will provide to all the contributors from our pocket. | |
Hardware tools and accessories | $ 100 | $600 | Additional hardware tools to test things and write accurate technical details. |
Donations | $700 | $700 | Donations to OpenSource projects Sphinx which we are using to create the documentation. |
International Shipping | $120 | $760 | Total allocation for package delivery via DDP (Demand Duty Paid) intercom so that technical writers and volunteers get the package without headache of customs duty (taxes already paid by us under DDP). |
Total | - | $13240 |
- |
Additional information
- Previous experience with technical writers or documentation: Jason and Robert mentored contributors before to launch the initial release of 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 them enough experience to handle all the technical writers during GSoD 2023.
- 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.