Improving Documentation

License badge Weaviate on Stackoverflow badge Weaviate issues on Github badge Weaviate v1.16.5 version badge Weaviate v1.16.5 version badge Weaviate total Docker pulls badge


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 (Jekyll) 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.

Documentation folders

The documentation repository is structured as below:

β”œβ”€β”€ .github/                            #contains GitHub template files for issues and pull requests
β”œβ”€β”€ _data/                              #contains site's data files
β”œβ”€β”€ _includes/                          #contains numerous templates like header, footer, navbar, etc
β”‚   β”œβ”€β”€ benchmarks/                     
β”‚   β”œβ”€β”€ code/                     
β”œβ”€β”€ _layouts/                           #contains layouts for documentation and posts
β”œβ”€β”€ _posts/                             #contains blog posts
β”œβ”€β”€ _python/                        
β”œβ”€β”€ developers/                         #contains documentation
β”‚   β”œβ”€β”€ assets/                         #contains clipboard functionality
β”‚   β”œβ”€β”€ contributor-guide/              #contains contributor guide for Weaviate
β”‚   β”œβ”€β”€ weaviate/                       #contains files and folder for product documentation 
β”œβ”€β”€ img/                                #contains all site images
β”œβ”€β”€ js/                                 #contains JS files for various functionalities
β”œβ”€β”€ resources/                          #contains additional site pages like gsoc, gsod
β”œβ”€β”€ .editorconfig
β”œβ”€β”€ .gitignore
β”œβ”€β”€ .travis.yml                         #for continuous integration and deployment
β”œβ”€β”€ 404.html                            #custom not found page.
β”œβ”€β”€ CONTRIBUTING.md
β”œβ”€β”€ CODE_OF_CONDUCT.md
β”œβ”€β”€ Gemfile                             #contains gem dependencies for the site.
β”œβ”€β”€ Gemfile.lock
β”œβ”€β”€ LICENSE
β”œβ”€β”€ README.md
β”œβ”€β”€ _config.yml                         #contains Jekyll settings for the site
β”œβ”€β”€ _config_dev.yml                     #for site build time improvement
β”œβ”€β”€ blog.md                             #main blog page of the site
β”œβ”€β”€ index.md                            #homepage of weaviate.io
β”œβ”€β”€ podcast.md                          #podcast page of the site
β”œβ”€β”€ product.md                          #product page of the site
β”œβ”€β”€ resources.md                        #resource page of the site
β”œβ”€β”€ robots.txt                          #tells search engine crawlers which URLs are accesible
β”œβ”€β”€ run.sh                              #script for previewing the site
└── setup.sh                            #script for setting up the website

The content is stored on HTML and Markdown (.md) files, and YAML files are used for configurations.

Liquid syntax

Jekyll uses the Liquid templating language to process templates. To learn more about Liquid, check out the official Liquid Documentation.

Here are some syntax which we commonly use in our code:

  • if conditional

This executes the block of code only if the given condition is true. For example:


Published on {{ page.date | date: '%B %d, %Y' }}
{% if page.canonical-name %}
    originally on
    <a href="{{ page.canonical-url }}" target="_blank">{{ page.canonical-name }}</a>
{% endif %}

  • for loop

The for statement executes a block of code repeatedly. For example:


{% for integration in site.data.integrations %}
    <a class="dropdown-item" href="/product.html#{{ integration.name | downcase }}">
        {{ integration.name }} ({{ integration.type }})
    </a>
{% endfor %}

  • Include

The above tag is used to insert a already rendered file within the current template. For example:


{% include docs-current_version_finder.html %}

  • Assign

The assign tag is used to create a new variable. For example:


{% assign sortedResources = site.data.podcasts | sort: 'date' %}