Skip to content

Latest commit

 

History

History
145 lines (98 loc) · 8.74 KB

contributing_docs.mdx

File metadata and controls

145 lines (98 loc) · 8.74 KB
Raw
title description sidebarDepth
Contributing to our documentation — Meilisearch documentation
The Meilisearch documentation is open-source. Learn how to help make it even better.
3

Contributing to our documentation

This documentation website is hosted in a public GitHub repository. It is built with Next.js, written in MDX, and deployed on Vercel.

Our documentation philosophy

Our documentation aims to be:

  • Efficient: we don't want to waste anyone's time
  • Accessible: reading the texts here shouldn't require native English or a computer science degree
  • Thorough: the documentation website should contain all information anyone needs to use Meilisearch
  • Open source: this is a resource by Meilisearch users, for Meilisearch users

Documentation repository and local development

The Meilisearch documentation repository only stores the content of the docs website. Because the code that makes up the website lives in another repository, it is not possible to run a local copy of the documentation.

Handling images and other static assets

When contributing content to the Meilisearch docs, store screenshots, images, GIFs, and videos in the relevant directory under /assets.

The build process does not currently support static assets with relative paths. When adding them to a document, make sure the asset URL points to the raw GitHub file address:

\!\[Image description\]\(https://raw.githubusercontent.com/meilisearch/documentation/[branch_name]/assets/images/[guide_name]/diagram.png\)

How to contribute?

Issues

The maintainers of Meilisearch's documentation use GitHub Issues to track tasks. Helpful issues include:

  • Notify the docs team about content that is inaccurate, outdated, or confusing
  • Requests for new features such as versioning or an embedded console
  • Requests for new content such as new guides and tutorials

Before opening an issue or PR, please look through our open issues to see if one already exists for your problem. If yes, please leave a comment letting us know that you're waiting for a fix or willing to work on it yourself. If not, please open a new issue describing the problem and informing us whether you want to work on it or not.

We love issues at Meilisearch, because they help us do our jobs better. Nine times out of ten, the most useful contribution is a simple GitHub issue that points out a problem and proposes a solution.

Creating your first issue

To open an issue you need a GitHub account. Create one if necessary, then follow these steps:

  1. Log into your account
  2. Go to the Meilisearch Documentation repository
  3. Click on "Issues"
  4. Use the search bar to check if somebody else has reported the same problem. If they have, upvote with a 👍 and don't create a new issue!
  5. If no one reported the problem you experienced, click on "New issue"
  6. Write a short and descriptive title, then add a longer summary explaining the issue. If you're reporting a bug, make sure to include steps to reproduce the error, as well as your OS and browser version
  7. Click on "Submit new issue"
  8. A member of our team should get back to you shortly
  9. Enjoy the feeling of a job well done! 🎉

Pull requests

You can also improve the documentation by making a pull request.

Pull requests ("PRs" for short) are requests to integrate changes into a GitHub repository. The simplest way to create a PR on our documentation is using the "Edit this page" link at the bottom left of every page.

Pull requests are particularly good when you want to:

  • Solve an existing issue
  • Fix a small error, such as a typo or broken link
  • Create or improve content about something you know very well—for example, a guide on how to integrate Meilisearch with a tool you have mastered

In most cases, it is a good idea to create an issue before making a PR. This allows you to coordinate with the documentation maintainers and find the best way of addressing the problem you want to solve.

Creating your first PR

To create a PR you need a GitHub account. Create one if necessary, then follow these steps:

  1. Go to the documentation page you'd like to edit, scroll down, and click "Edit this page" at the bottom left of the screen. This will take you to GitHub
  2. If you're not already signed in, do so now. You may be prompted to create a fork
  3. Use GitHub's text editor to update the page
  4. Scroll down until you reach a box named "Propose changes"
  5. Fill in the first field to give your PR a short and descriptive title—for example, "Fix typo in search API reference"
  6. Use the second field to add a more detailed explanation of the changes you're proposing
  7. Click the "Propose changes" button to continue. You should see a page that says "Comparing changes"
  8. Make sure the base repository is set to meilisearch/documentation and the base branch is set to main. You can ignore the remaining fields
  9. This screen will also show you a "diff", which allows you to see the changes you made compared to what's currently published on the documentation website
  10. Click "Create pull request"
  11. Congrats, you made your first PR! A documentation maintainer will review your pull request shortly. They may ask for changes, so keep an eye on your GitHub notifications
  12. If everything looks good, your work will be merged into the main branch and become part of the official documentation site. You are now a Meilisearch Contributor! 🚀

How we review contributions

How we review issues

When reviewing issues, we consider a few criteria:

  1. Is this task a priority for the documentation maintainers?
  2. Is the documentation website the best place for this information? Sometimes an idea might work better on our blog than the docs, or it might be more effective to link to an external resource than write and maintain it ourselves
  3. If it's a bug report, can we reproduce the error?

If users show interest in an issue by upvoting or reporting similar problems, it is more likely the documentation will dedicate resources to that task.

How we review PRs

For reviewing contributor PRs, we start by making sure the PR is up to our quality standard.

We ask the following questions:

  1. Is the information accurate?
  2. Is it easy to understand?
  3. Do the code samples run without errors? Do they help users understand what we are explaining?
  4. Is the English clear and concise? Can a non-native speaker understand it?
  5. Is the grammar perfect? Are there any typos?
  6. Can we shorten text without losing any important information?
  7. Do the suggested changes require updating other pages in the documentation website?
  8. In the case of new content, is the article in the right place? Should other articles in the documentation link to it?

Nothing makes us happier than a thoughtful and helpful PR. Your PRs often save us time and effort, and they make the documentation even stronger.

Our only major requirement for PR contributions is that the author responds to communication requests within a reasonable time frame.

Once you've opened a PR in this repository, one of our team members will stop by shortly to review it. If your PR is approved, nothing further is required from you. However, if in seven days you have not responded to a request for further changes or more information, we will consider the PR abandoned and close it.

If this happens to you and you think there has been some mistake, please let us know and we will try to rectify the situation.

Contributing to Meilisearch

There are many ways to contribute to Meilisearch directly as well, such as:

There are also many valuable ways of supporting the above repositories:

  • Giving feedback
  • Suggesting features
  • Creating tests
  • Fixing bugs
  • Adding content
  • Developing features