Skip to main content

Improving Documentation

Introduction​

Maintaining consistent, accurate and readable documentation is way to improve the user experience for everybody, including experienced users.

The truth is that while we try our best, mistakes happen (we are not perfect! 😅). And if you found something difficult to understand, others may have too, which presents an opportunity for improvement.

So if you spot any typos, errors, unclear explanations, missing references or anything that stands out, please let us know, and we can work on it together.

How Weaviate documentation is built​

Weaviate's documentation is built with a static site builder (Docusaurus) with data from our GitHub repository. Before you get started, we suggest you set up a local development environment first. This will allow you to preview any changes on your computer as you work on it.

For instructions on setting up the development environment, please take a look at this README file.

Once your local environment is set up, you can make your proposed changes, preview them locally, and submit them for review.

MDX syntax​

You will notice MDX / React syntax throughout this site. Docusaurus has built-in support for MDX v1, which allows you to write JSX within your Markdown files and render them as React components.

Read this Docusaurus page for more information.

Infima styling​

This site uses Infima for styling. Read this Docusaurus page for more information.

Tests​

We've adopted a code sample structure that lets us both test and expose the samples without duplicating code. This is done using the FilteredTextBlock component, which loads arbitrary files and extract lines between a start marker and an end marker. You'll see statements like import JSCode from '!!raw-loader!/_includes/code/howto/search.basics.ts'; in .md files, followed by

<FilteredTextBlock
  text={JSCode}
  startMarker="// BasicGetJS"
  endMarker="// END BasicGetJS"
  language="js"
/>

To learn how to run tests, see the README.md file in /tests/.