-
Notifications
You must be signed in to change notification settings - Fork 1
Project Proposal
- Educate a diverse cohort of young R developers to acquire the technical knowledge and skills required to participate in the continuous integration of R packages into the R ecosystem.
- Develop a new documentation solution with a Quarto website that is user-friendly for new R package maintainers on CRAN.
- Identify common CRAN submission issues and create a framework of "problems" and "solutions" that are easy to implement and discover.
The CRAN Team often sees the same issues cropping up in package (re-)submissions to CRAN. The solution may be documented in the Writing R Extensions manual or the CRAN Repository Policy, however, it may take package maintainers some time to work out how to fix their package.
For new submissions, this can mean a long delay in getting a nearly finished package onto the official repository. For re-submissions, maintainers may miss the deadline set by the CRAN Team to fix the package, meaning a package can be temporarily or permanently archived, affecting users and other package developers. These all present a high barrier of entry to developing and submitting R packages to CRAN for new R developers.
The current R ecosystem of package development is filled with diverse practices and standards on CRAN have changed over time. By creating user-friendly documentation, new R package maintainers can expand their technical skillset by discovering the "solution" to their "problem" on their own resulting in a quicker submission and publication process. This may also increase their confidence and commitment to contribute and share their open source code on CRAN.
This project will create a "cookbook style" problem and solution documentation that directly documents how to fix common issues, making it easier for maintainers to respond to feedback from the CRAN Team.
- Gathering data from recent CRAN (re-)submissions to identify common issues.
- Setting up scaffolding for the documentation with Quarto.
- Identifying any existing documentation that can be referenced in writing solutions.
- Writing new documentation in easy to navigate problem/solution format.
- Sharing with the community of package maintainers and revising in the light of feedback.
- Integrating with the CRAN Team's workflow for submissions.
- Developing a training webinar for the new documentation.
- Extensive re-writes of material in the Writing R Extensions manual or the CRAN Repository Policy - the new documentation should complement rather than replace these resources.
- Milestone 1
- Top N most common CRAN (re-)submissions issues are identified
- The Quarto website scaffolding is established on GitHub
- Milestone 2
- Draft 1 of the Quarto website is presented to the CRAN Team
- Collect feedback from diverse R communities (e.g. R-Ladies) of the first draft
- Milestone 3
- Draft 2/Final release of the Quarto website
- Begin measuring the effectiveness of the Quarto website as it pertains to improving the skillset of R maintainers
- Publish a case study/blog post
- Develop a training webinar for the new documentation, targeted for a diverse group of interested package maintainers
This project will be a benefit to the R community if it expedites the time it takes for package maintainers to solve common problems, clearing the pathway for CRAN acceptance and reducing repeat problems.
We would consider the project successful if:
- We are able to host a training webinar(s) for a diverse group of interested package maintainers.
- The documentation covers at least the top 10 issues identified by the CRAN Team.
- Website analytics show that the documentation is being viewed by people outside the project team.
- Documented problems occur less frequently as package maintainers proactively check against these issues.
- The CRAN Team begin to directly link to documented problems/solutions when package (re-)submissions are rejected.
We have two strong technical writers for this project, one is currently working as a part-time assistant on the CRAN Team with responsibility for handling CRAN submissions and the other is a data science consultant with substantial cross-functional experience including project management, CRAN package development and technical documentation writing.
- Jasmine Daly (@jasdumas): Principal Consultant & Founder of Daly Analytics, maintainer of 2 CRAN packages | Linkedin | Website
- Beni Altmann (@Baltmann01): Student, assistant member of the CRAN Team working on CRAN submissions
The writers will benefit from the mentoring and advice of a Steering Committee with expertise in CRAN package development and technical writing:
- Heather Turner (@hturner): member of the R Foundation, former R Journal Editor, maintainer of 4 CRAN packages, has run several workshops on R package development.
- Bettina Grün (@bettinagruen): member of the R Foundation, Journal of Statistical Software Editor-in-Chief, former R Journal Editor, maintainer of 5 CRAN packages, manager of the two assistants on the CRAN Team working on CRAN submissions.
- Gwynn Gebeyehu (@nzgwynn) data scientist, former lecturer and academic researcher, has experience of technical writing for range of audiences. R user since 2002 with package development experience.
- Slack: The project members will have access to the R-contributors Slack group to communicate asynchronously.
- Video calls: The writers expect to meet every two weeks, with the Steering Committee expected to join at least once a month (not necessarily at the same time).
- Writing: The project members will conduct all writing and development on GitHub on a dedicated repository.
- Feedback: The project members will develop surveys to obtain necessary project feedback from the CRAN Team and the relevant R community which includes potential new R package maintainers.
We estimate that this work will take seven months to complete. The technical writers will start research & development over staggered periods, with Beni Altmann (CRAN assistant) working 150 hours over May to October and Jasmine Daly working approximately 16 hours a month from June to November.
| Dates | Action Items | People |
|---|---|---|
| May 2024 | Gathering data on common issues, prioritising | Junior writer, mentors |
| June - July 2024 | Create first version of documentation | All |
| August - September 2024 | Test with package maintainers and CRAN Team, update based on feedback | All |
| October - November 2024 | Release second version of documentation, write case study/blog, promote within R community, host training webinar(s) | Senior writer, mentors |
| Budget item | Amount | Running Total | Notes |
|---|---|---|---|
| Beni Altmann | $4500 | $4500 | Writing, research and development time |
| Beni Altmann | $400 | $4900 | We will cover registration and travel support for the Junior Writer to attend useR! 2024 |
| Jasmine Daly | $10,500 | $15,400 | Writing, research and development time, project management |
| Gwynn Gebeyehu | $500 | $15,900 | Only 1 Volunteer stipend required |
After the completion of each milestone an invoice will be submitted to the R Consortium.
| Milestone 1 | Milestone 2 | Milestone 3 | |
|---|---|---|---|
| Beni Altmann | 25% of budget item ($1225) | 50% of budget item ($2450) | 25% of budget item ($1225) |
| Jasmine Daly | 25% of budget item ($2625) | 50% of budget item ($5250) | 25% of budget item ($2625) |
| Gwynn Gebeyehu | 100% of budget item ($500) |
Previous experience with technical writers or documentation: Heather Turner, a member of the Steering Committee, co-mentored a project funded by the R Foundation that produced the initial version of the R Dev Guide. The project took place over 3 months, with the co-mentors (based in the UK and the US) meeting the technical writer (based in India) for 30 minutes each week to discuss the documentation plans and advise on content. The project benefited from the input of a wide group of volunteers belonging to the R Contribution Working Group. Co-mentors or volunteers reviewed pull requests to the documentation and provided additional support through the R-devel Slack workspace. We anticipate similar participation from the community in this project. The Steering Committee have a wealth of experience related to technical documentation, including writing documentation for R packages published on CRAN, contributing content for the R Project website, editing the R Journal and Journal of Statistical Software, and authoring teaching materials on data science and R programming, including R package development.