Contributing to our documentation

This documentation website is hosted in a public GitHub repository (opens new window). It is built with VuePress (opens new window), written in MarkDown (opens new window), and deployed on Netlify (opens new window).

Our documentation philosophy

Our documentation aims to be:

• Efficient. We don’t want to waste anyone’s time.
• Accessible. Reading this shouldn’t require native English or a computer science degree.
• Thorough. Behavior that isn’t documented or is documented incorrectly, we consider broken.
• Open source. This is a resource by MeiliSearch users, for MeiliSearch users.

How to contribute?

Issues

On the MeiliSearch documentation team, GitHub Issues (opens new window) are the primary tool we use to track tasks. They’re like elements in our to-do list. Here are some good uses for issues:

• A detailed bug report
• A request for a new technical feature (e.g. dark mode, versioning, etc.)
• A request for new content (e.g. a tutorial, guide, or explanation)
• A helpful suggestion for the future of the documentation

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

All you need to create an issue is a GitHub account (opens new window).

1. Log into your account.
2. Go to the MeiliSearch Documentation repository (opens new window).
3. Click on “Issues”.
4. Use the search bar to make sure nobody else has reported your issue already. If somebody has, give them an upvote 👍 and don’t create that issue!
5. Click “New issue”.
6. Fill in a short, descriptive title and longer summary of your problem or suggestion. 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 “Submit new issue”.
8. A member of our team should get back to you shortly with feedback.
9. Enjoy the feeling of a job well done! 🎉

Pull requests

Sometimes, it’s faster to fix a problem yourself than explain it to us. In those cases, rather than create an issue, you should make a pull request (opens new window).

Pull requests (“PRs” for short) are requests to integrate your changes into a GitHub repository. The simplest way to create a PR on our documentation is by using the “Edit this page” link at the bottom left of every page. See below for more detailed instructions.

Pull requests are particularly good for:

• Fixing a small error, such as a typo, broken link, or bad word choice.
• Making a change that you are particularly qualified for (such as creating a guide for some software that you have mastered).
• Solving an existing issue (opens new window)!

Unless your PR is really small, we recommend you first create an issue to confirm that it’s worth your time and that nobody else is working on it already.

Creating your first PR

There are many ways to create pull requests, but we’ll cover the simplest method for creating a PR on these docs. Feel free to try it on this page!

All you need to continue is a GitHub account (opens new window).

1. On the documentation page you’d like to edit, scroll to the bottom and click “Edit this page” on the left. 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 (opens new window)—if so, do it.
3. Use GitHub’s text editor to make the change you want.
4. Scroll down to where it says Propose changes. In the first text box, write a short description (e.g. “Fix typo”). In the second text box, write a longer description of your changes if necessary.
5. Click Propose changes to continue. You should see a page that says Comparing changes. This screen is prompting you to create a pull request.
6. Make sure the base repository is meilisearch/documentation and the base is master. Don’t worry about the other two boxes—they automatically target the changes you just made.
7. Below, you can see the changes you made compared to the master branch (what’s currently published on docs.meilisearch.com (opens new window)). When you’re ready, click Create pull request.
8. Congrats, you made your first PR! Someone from the documentation team will review your pull request shortly. They may ask for changes, so keep an eye on your GitHub notifications.
9. If everything looks good, your work will be merged into the master branch and become part of the official documentation site. You are now a MeiliSearch Contributor! 🚀

How we review contributions

For reviewing issues, we consider a couple criteria:

1. Is this task a priority for the documentation team?
2. Is our documentation the best place for this information? Sometimes an idea for new content might work better on our blog than the docs, or it might be more effective to link to an external resource than write it ourselves.
3. Can we reproduce this error?

If multiple people create similar issues (or upvote 👍 an issue to show suport), that makes us more likely to divert resources towards that task.

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? Are explanations and examples clear?
3. Is the English simple enough to be understood by a non-native speaker?
4. Is the grammar perfect? Are there any typos?
5. Can it be more efficient?
6. Should any new information be added or changed somewhere else in the documentation?
7. In the case of new pages, has the page been added in the right location? Should it be linked elsewhere in the documentation?

Nothing makes us happier than getting a thoughtful, helpful PR that saves us time and effort and makes the documentation even stronger. Thank you in advance for your contribution!