Google Season of Docs 2024 Proposals
Advancing Documentation Quality with SciCookie - Open Science Labs #
Open Science Labs (OSL) actively supports open-source development, and the principles of open science. Our Incubator Program aids in the development of open-source projects and a plethora of processes to benefit the community across various disciplines. We strongly believe that effective documentation is essential for success and expansion. Therefore, participating in the Google Season of Docs, will enable us to enhance our documentation quality. In turn, making our projects more user-friendly and easier to contribute to. It is our priority to achieve enhanced documentation processes, following with the integration to all new projects. These improved documentation standards will shape a project template named “SciCookie”.
About Open Science Labs #
OSL is dedicated to advancing scientific research through collaboration, innovation, and education. Our mission is to foster a more inclusive, transparent, and accessible scientific community; empowering researchers, educators, and students to contribute significantly towards scientific advancements. OSL encourages partnership, modernization, and learning within the scientific community. Thus, OSL offers Project Incubation, Partnerships, and an Internship Program to rising talents, all while upholding the principles of openness and accessibility.
About the Project #
Project's Problem #
Maintaining high-quality documentation is challenging, especially when initiating a new project and establishing its foundational documentation structure. SciCookie, leveraging cookieninja (a cookiecutter fork) as its backend, facilitates the creation of a robust initial structure for new projects. It incorporates recommendations from pyOpenSci to optimize the project template, encouraging adherence to best practices from the outset. However, SciCookie's current documentation structure is rather simplistic. Undoubtedly, here's a clear need for guidelines. These contributions would assist writers and boost quality and effectiveness.
Project's Scope #
This project aims to develop comprehensive guidelines for all documentation and evidence recording. Moreover, the scope would include structural refining of the existing SciCookie template. Once OSL applies these guidelines to at least one Incubator Project, (as a pilot to validate the recommendations), the process would be complete.
Deliverables #
- Documentation Guideline: Establish guidelines for creating effective and comprehensive documentation for Python projects.
- mkdocs Guideline: Formulate specific recommendations for using mkdocs with material, including configuring menus, sub-menus, table of contents, and blog posts.
- Pilot Project Implementation: Apply both sets of guidelines to a selected incubator project as a practical implementation test.
- Update SciCookie: Integrate these guidelines into the SciCookie template.
Measuring Success #
Success will be evaluated through a Google Forms survey, seeking feedback on the ongoing work. We aim for at least 75% positive feedback, focusing on content quality, information completeness, documentation aesthetics, and functionality.
Requirements #
Technical Writer #
Required:
- Proficient in English
- Experienced in documentation organization
- Able to communicate with community members
- Comfortable with Git, GitHub, and pull request workflows
- Familiarity with Python and mkdocs
Volunteers #
@xmnlab - Ivan, the main point of contact, has contributed extensively to documentation and setup for incubator projects.
@bluexblooded - Victoria is a professional writer experienced in covering a wide variety of topics.
Timeline #
The project span is 6 months; from May to November 2024. This timeline considers the existence of a dedicated technical writer working an average of 10 hours per week. Activities include participating in community meetings, and promoting OSL projects.
| Month | Task and Milestones |
|---|---|
| April | Start recruiting process for hiring a technical writer. |
| May | Contract a technical writer; Orientation and project initiation: Introduce the technical writer to the OSL community and outline the project scope. |
| June | Draft documentation guidelines and mkdocs configuration recommendations. Start a pilot project implementation. |
| July | Apply guidelines and configurations to a pilot project. Gather an initial feedback from OSL community. |
| August | Refine the documentation based on feedback. Begin the integration of guidelines into the SciCookie template. |
| September | Applyt final review and adjustments to the documentation and mkdocs configurations. Continue the integration into the SciCookie project. |
| October | Finalize and publish all changes to the pilot project documentation. Finalize the integration into the SciCookie project. |
| November | Evaluate the project success through community feedback. Document lessons learned and celebrate achievements. |
Project Budget #
The budget is based on a 10-hour weekly commitment over 6 months, with adjustments as necessary, at a rate of $30 USD/hr.
| Budget Item | Quantity | Amount | Running Total |
|---|---|---|---|
| Technical writer | 1 | 7200.00 USD | 7200.00 USD |
| Volunteer stipends | 2 | 500.00 USD | 1000.00 USD |
| Sub-total | - | - | 8200.00 USD |
| OC Overhead | - | 10% | 820.00 USD |
| TOTAL | - | - | 9020.00 USD |
**OC: Open Collective
How to Apply #
Interested technical writers can apply for participation in the Google Season of Docs with Open Science Labs by following these steps:
- Join the Open Science Labs channel on Discord.
- Explore the SciCookie documentation page, focusing on the sections about Contributing, User Guide, and Installation. Getting acquainted with the overall documentation structure will be beneficial.
- Acquire some familiarity with Python and documentation technologies like mkdocs to better understand the user base and their challenges.
- Engage with us on Discord by introducing yourself. We are eager to share more details and answer any questions.
Contact Information #
To express your interest in this project, please send an email to team@opensciencelabs.org, including links to your technical writing samples, portfolio, or CV.
Ensure your application is submitted by 10 May 2024, 23:59 UTC.
The selected applicant will be announced by 18 May.
For further inquiries, our Discord server is an open channel for questions: https://opensciencelabs.org/discord.
This text is licensed under a
Creative Commons Attribution-ShareAlike 4.0 International License
.