Skip to main content

Google Season of Docs 2022 - Proposal

This is a technical writing proposal for participating in Google Season of Docs 2022. Season of Docs gives technical writers the opportunity to gain experience in open source by contributing to documentation.

This page contains Weaviate's proposal to participate in Season of Docs 2022. In case our proposal is accepted by Google, we will be looking for Weaviate's community members with technical writer skills to help with the project described below.

Technical writers interested in working on this project should send an email to careers AT semi.technology, before May 1st. Please include links to your technical writing work or portfolio/résumé/CV.

Proposal Title - Create a comprehensive contributor onboarding guide for Weaviate

About Weaviate​

Weaviate is an open-source vector database that stores both objects and vectors, allowing for combining vector search with structured filtering with the fault-tolerance and scalability of a cloud-native database, all accessible through GraphQL, REST, and various language, clients. SeMI Technologies is the company behind Weaviate, and has been working on this project for around 3 years now.

Weaviate is a unique open-source project in the vector search world. The community is growing rapidly, and we see that the number of community contribution is increasing.

The problem that Weaviate solves​

In machine learning, e.g. recommendation tools or data classification, data is often represented as high-dimensional vectors. These vectors are stored in so-called vector databases. With vector databases you can efficiently run searching, ranking and recommendation algorithms. Therefore, vector databases became the backbone of ML deployments in industry. Weaviate is a vector database that enables combining vector search with structured filtering. Weaviate can be used with out-of-the-box or custom trained ML models to do semantic search, one-shot classification, question answering, NER, multi-modal search, and much more, on a large scale.

Read more about Weaviate here.

Users and contributors​

Weaviate can be used to solve industry-agnostic data problems, so our current users come from multiple disciplines. Current users range from companies who are using Weaviate for product search and categorization in e-commerce to companies who use Weaviate to search through video captions, and from users who use Weaviate to do image-text search to users who use Weaviate to browse through scientific papers.

Current contributors to Weaviate are mainly people who make their own Weaviate module (for example to use a new type of ML model with Weaviate).

About the project​

The project's problem​

We have a Weaviate documentation and a contributors guide. Currently, the contributors guide is very limited. Good documentation on how to get started on contributing to Weaviate is lacking. The pages that are in the current guide helps Weaviate developers who have a good amount of background knowledge and have been contributing to Weaviate before, but it is hard to get started as an unexperienced contributor.

We would like to have a contributors guide that is a complete guide that helps new contributors from the beginning until the end. This includes pages about how to get involved & onboarding, how to open a first issue on GitHub, how to structure Pull Requests and more. Ideally, the contributors guide will, like Weaviate's documentation, also contain tutorials with examples and perhaps even videos (can be outside the scope of this project).

The goal of having better contributor documentation is to lower the barrier to contribute for whoever is interested in helping Weaviate.

The project's scope​

For this project the technical writer will:

  • Audit the existing contributors guide (and Weaviate's documentation where pieces of contributors guidelines are scattered) to create an overview of existing docs and understand the current gaps and shortcomings.
  • Work with community users to
    • Identify user groups that are interested in contributing (based on background and/or experience and/or contribution goal)
    • Research what could be improved on the current guides (e.g what is lacking)
    • Validate whether written content is understood by the community and subsequently iterate on the content incorporating the feedback
  • Create guides focused to each of these different groups
  • Create/improve general guidelines on how to make issues on GH and how to structure PRs
  • Create a “cheat sheet” to help contributors understand the process for contributing
  • Create 'onboarding' guidelines (how to get started with developing Weaviate, development setup, etc)
  • Create tutorials/walkthroughs with examples of how to contribute

Measuring your project’s success​

Weaviate's base of contributors is currently very small. PRs are mostly from previous contributors, who are affiliated with SeMI Technologies (the company behind Weaviate). By improving the contributor documentation the goal is to lower the barrier to contribute for whoever is interested in helping Weaviate. We will measure success by the following metrics.

  1. The number of page views of contributor documentation
  2. The number of PRs to Weaviate by developers not related to SeMI
  3. The number of new contributors (PRs done by people who didn't contribute to Weaviate before)

The project will be classified successful if the following goals are met after the new docs are live:

  1. Contributor documentation page views increases with 50%
  2. The number of PRs to Weaviate by developers not related to SeMI increases with 20%
  3. The number of new contributors (PRs done by people who didn't contribute to Weaviate before) increases with 15%

Timeline​

The project will start in April 2022 and end in November 2022. The first month will be spend on hiring the technical writer and May will be dedicated to orientation.

  • April: Hiring
  • May: Orientation & setup audit plan (including user study)
  • June:Audit & Create writing plan
  • July-September: Write documentation
  • October: Gather feedback from community and incorporate feedback in docs
  • November: Complete the project

Project budget​

  • Technical writer: $6000
  • Volunteer stipend: $500
  • Videos to support documentation/tutorials & to share to community: $500
  • Total: $7000

What skills would a technical writer need to work on this project?​

Must have:

  • Familiarity with GitHub (or willingness to work through GitHub tutorials)

Nice to have:

  • Familiarity with writing in Markdown (or willingness to work through markdown tutorials)
  • Familiarity with Weaviate (or willingness to work through Weaviate tutorials)

Volunteers & Mentors​

Contact info​

Technical writers interested in working on this project should send an email to careers AT semi.technology, before May 1st. Please include links to your technical writing work or portfolio/résumé/CV.

Additional information​

Weaviate is selected to participate as mentoring organization in Google Summer of Code 2022, see our available projects here. Join our community slack to say hello, get to know the community or ask questions.