R‐Universe: Google Season of Docs Case Study - r-universe-org/gsod-2024 GitHub Wiki
Organization or Project Name: rOpenSci's R-Universe
Season of Docs Link: https://github.com/r-universe-org/gsod-2024/wiki/GSOD-2024-proposal:-Documenting-R-software-publication-with-R‐universe
Organization Description: R-Universe is rOpenSci’s platform for improving publication and discovery of research software in R. It serves as a global catalog of software, articles, and data found across R repositories. It is a software publication platform providing a fully automated pipeline for testing, building, and publishing R packages. It is also a meta-repository, providing common infrastructure for both individuals and organizations to manage custom R package repositories using their own approach to curation, release management, and quality control.
Authors: Noam Ross
Summary:
Although the R-universe project has been broadly adopted by developers, users, and organizations, our development has outpaced our documentation in recent years. We created a new documentation site for the R-universe project, http://docs.r-universe.dev, that consolidated fragmented documentation from across blog posts, issues, and R-Universe pages. We also created an interactive tour built in to the R-Universe interface that helps users navigate any package page. Developing documentation also helped us identify ambiguities in the interface and other areas of the site design or features that needed refinement or decisions made in order to document them properly. Now, with a base site and well-established documentation workflow, we are documenting more features as they are are developed. We continue to recieved feedback from users and developers to improve the documentation.
The project was successful in making a base site and documentation workflow that we are now using continuously as R-Universe features are developed.
We would recommend that other projects also consider the optimal time in the project arc to make a major investment in documentation, based around stages such as beta-release or tying it to adoption milestones or feature stability. We also recommend building in feedback from users early.
Project Description:
Project Proposal
We aimed to address the fragmented and incomplete documentation that hindered users from fully utilizing R-Univers's features. Our goals included consolidating content from various sources, organizing it around key concepts for developers and users, and ensuring comprehensive coverage of all features. Additionally, the project aimed to integrate cross-linking with existing resources, establish contribution guidelines, create a CI/CD pipeline for documentation updates, incorporate traffic analytics, and gather feedback from users and developers continuous improvement. The ultimate objective was to enhance the accessibility and usability of R-Universe, and enable participation of more developers in the future.
Proposal Creation Process
The project of developing comprehensive documentation for R-Universe had been on our mind for some time, as the project had been developing for several years and we understood that this item was backlogged. The challenge was in determining the best time to put in effort for this, as R-Universe's features and functionality were rapidly evolving and we did not want documentation to lag behind or lock in our approaces. However, by mid-2024 adoption of R-Universe was rapidly growing, including with new larger organizations looking to use R-Universe as a platform for their own projects, and we decided it was time collect the scattered documentation. At that point, our infrastrucure lead and techinical writer developed the scope of the project.
Budget
| Topic | Detail |
|---|---|
| How much money did you ask for? | $13,800 |
| How did you come up with this estimate? | Having worked with our technical writer before, we had a strong idea of their rates and time frame required for the project. |
| How many hours of work did you budget for the project? | 145 |
| How many hours of work were actually needed for the project? | 105, with additional follow-up work expected |
| What other expenses did you include in your budget? | Time for oversight and review by project leads. |
| Did you run into any budget surprises during the project (e.g. misestimates)? If so, please explain. | No |
Tech Writer Recruitment
Our primary technical writer, Maëlle Salmon, had alredy worked with our orgaznation for many years and has worked on documentation projects for rOpenSci, R-Hub, and R-Ladies in addition to being a prolific blogger on techinical topics, so was our natural choice as she was available. Working with a writer with an already deep knowledge of the organization and project was a natural choice and we developed the proposal and plan jointly.
Other participants
Maëlle worked hand in hand with R-Universe's leader developer, Jeroen Ooms, to identify areas that needed to be documented. We also recruited several developers and users to provide feedback on the new documentation site, both through individual consultations and requests for issues and pull requests to be filed.
Timeline
Collecting feedback from users and developers is a continuious process that has extended longer than we originally anticipated. We continue to recieve input that we are incoprorating into the release version of our documentation, and this will coninue beyond the the original project timeframe.
Deliverables
Planned Deliverables
Our only planned deliverable was the documenation site, https://docs.r-universe.dev, which is complete but undergoing revisions.
Unplanned Deliverables
During the process of the project, we decided to incorporate an interactive tour into the core R-Universe site to provide another form of entry-level documentation. All R-Universe package pages now include a guided tour making use of https://introjs.com.
We also developed a workkflow for programmatically geneterating the screenshots that we include in our documentation. This ensures that when documentation is auto-built, changes to the site layout and style remain up-to-date automatically. We published a guide to this workflow on our blog: https://ropensci.org/blog/2024/09/10/script-screenshots/
Metrics
- Project delivearble metrics:
- Website structure, CI, and preview pipeline complete ✅
- Documentation outline complete ✅
- Topics ported and rewritten from each of READMEs, blog posts, and FAQs ✅
- Missing topics identified and content written ✅
- Interviews completed Underway
- Site launched ✅
- Traffic: Current traffic to our documentation site is ~40 unique visits/day, about 3% of the traffice to the R-Universe platform itself, though we have engaged in minimal publicity as we wait for our original rounds of feedback. Traffic to R-Universe itself has increased by >60% since commencing the documentation project, though there have been other sources of growth such as a number of webinars and conference talks.
- Contributions: No external contributions as of yet. We expect these to occur only after the project is complete.
Analysis
Lessons Learned
| Topic | What We Did | What went well? | What could be improved? | Lessons Learned |
|---|---|---|---|---|
| Budget | Based on experience with similar projects | Good estimates, no surprises | ||
| Communication | Handled largely through GitHub issues, in weekly team meetings | Good communication within the team | ||
| Mentorship | See "Recruiting and Hiring" | |||
| Metrics | We identified metrics but they largely apply to after the project is complete | TBD | TBD | |
| Onboarding | See "Recruiting and Hiring" | |||
| Participants | Reached out for feedback in the last month of the project | Recruited readers | Late time frame for feedback | Start feedback process earlier |
| Project Deliverables | Had a very clear plan for the documentation scaffolding, but were open to new ideas | Got bootstrapped quickly, and also got a great value-add with the interactive tour | Could have laid out sub-goals more clearly | Set up a checklist of issues earlier |
| Project Management | Largely used existing processes and the project proposal as our guide | Work went largely smoothly | Designation of sub-tasks would have made metrics or progress more visible to track | Break down tasks to a checklist earlier in the process |
| Recruiting & Hiring | Used team member already familiar with the project | No onboarding needs, rapid startup | We did not expand the team or contributors | Build in new contributor participation and mentorship |