Hey everyone,
This is my project report for Google Season of Docs'22 with Weaviate. You can read about my initial experience about getting selected in GSoD'22 here. This project was declared successful amongst other projects in Google Season of Docs'22.
Project Abstract
In an open source project, a contributor onboarding guide gives potential project contributors a quick overview of how they might help with your project or study group. A newcomer may not know how to execute the aforementioned tasks successfully and efficiently if they do not have access to a solid contributor onboarding guide. These instructions can help secure a product's success by attracting new contributors, whose contributions will ensure the product's success. A great user guide simply takes that communication and organizes it into a framework that everyone can use to achieve success.
Participants
The project team members on this project were:
- Asmit Malakannawar – GSoD Student – Technical Writer
- Sebastian Witalec – GSoD Mentor – Developer Advocate
Pull Requests
List of PRs that include more details and discussion:
Deviations From Original Proposal
In my initial proposal, I solely proposed the creation of a contributor's guide. But as the project team worked on the documentation updates, it became apparent that the tooling (based on Ruby and Jekyll) used to build Weaviate docs was a significant obstacle for new contributors, as it was slow and difficult to set up.
To address that, I researched and experimented with other open-source tools for building documentation sites. As a result, we decided to move all of our structured documentation to Docusaurus, enabling contributors and the Weaviate team to work on the documentation with ease.
As a proof of concept, we created a sample site and deployed it on Vercel. Here are the links to the repository and the PoC website:
Timeline
Here are some milestones from the project timeline.
June - July
Audited the current Contributor’s Guide and prepared a list of suggestions.
Created the mockups on how a contributor's guide should look, with a list of pages and content the final Contributor’s Guide should contain.
August
Created a writing plan, with the step by step process of writing a beginner friendly doc.
Started the work on Contributor’s Guide.
Added issue and PR templates.
September
Completed the first draft of the Contributor's Guide .
Compared multiple online documentation options and selected Docusaurus.
October
Created a proof of concept for Docusaurus and iterated it based on reviews.
Checked the documentation for errors and typos.
November
- Project approved by the mentor and the Weaviate team.
Results
- Created a detailed contributor’s guide. Including detailed guides on basic git and GitHub workflow.
- Improved overall contributor experience – not only for beginners but also for current contributors.
- Made navigation easier by pointing contributors in the right direction.
- Updated GitHub issue and PR templates to make it easy for contributors to contribute to the documentation
My experience working with the team!
My involvement with Weaviate and the Google Season of Docs internship both helped me advance my knowledge of technical documentation. I gained a lot of knowledge about working with others, understanding a startup, and identifying opportunities to contribute. I've never had the chance to collaborate with an emerging open-source company more frequently. I appreciate the opportunity to work with Weaviate’s team on this project.
The project gave me numerous chances to brush up on my current knowledge of React, Docusaurus, and Jekyll, to mention a few, while working on the project. While the GSoD 2022 project comes to an end, Weaviate's documentation journey will continue.
Summary
Overall the project was a success, and we achieved our documentation deliverables.
We also started working on a new documentation site, making it a lot easier for anyone to contribute to Weaviate and our docs.
I want to give big thanks to Weaviate and especially my mentor Sebastian – for guiding me throughout this project – and to GSoD – for organizing such a fantastic project!
Top comments (0)