Improve contributing documentation

[curquiza]

Hello @meilisearch/docs-team 📚 👋

Not something really urgent since you don't participate in Hacktoberfest, but I see some parts in the repo that could be improved regarding the common way of structuring an open source repository.

1. We could add a CONTRIBUTING.md -> it's really common to look for it when you want to contribute. This file is definitely a dedicated place when talking to people creating PRs, which can be convenient as a maintainer of the repo!

2. We could rethink the README. README.md and CONTRIBUTING.md files are indeed two different files with two different purposes. a. README.md is to explain the purpose of the project (maintaining the Meilisearch docs), some interesting details about it (when the project is updated/deployed for instance) and how to use it (in your case, the users just need to go to the docs website). You can also add some information about Meilisearch in general since the repo belongs to an awesome company. b. CONTRIBUTING.md is to detail how to RUN the project in order to contribute to it. No need to install yarn to use the docs, however, if you want to contribute, you have to. You also need to add your contribution rules and information ("the docs team will review asap" for instance). c. The landing README.md and CONTRIBUTING.md are good examples of what kind of README/CONTRIBUTING we could expect.

3. This one is mainly an internal problem, but it could be the same for other external people: we are now used to using the main branch, not master. It's not easy to switch from this repo to ours, I have trouble with it anytime I try to fetch main 😂 -> done

I noticed you have one of the most contributed repositories (regarding the merged PRs) in the Meilisearch organization! 💪 Well done! And that's why I think it's important to help you improve some parts of the repo to better fit the common contributing expectations. Plus, I'm sure it could help you as a maintainer of the repository. Your current way of handling contributions is already good of course, I only reconsider the "structure" of the repo regarding the expected contributing files 😇

I would love to know your thought about it, and of course, I'm here to discuss and help you implement/change anything ❤️

[maryamsulemani97]

Also add:

• Code sample naming process
• Vale instructions
• Dos and don'ts from the style guide

[dichotommy]

In the end, this issue was not solved as part of the preparation for v1.0.

After conducting research and discussing it within the team, we determined that most open-source documentation sites do not use a CONTRIBUTING.md file. Instead, the common pattern is to explain how to contribute to a documentation site on the documentation site itself. This makes sense, and matches our own approach.

We have decided to improve our own contributing documentation, starting with a review (#2147) and continuing by expanding it to include some information on running the docs which is currently present in the README (#2150).

Afterwards, we are considering expanding the contribution documentation to include some or all of the following:

Info on prerequisites for contributing to the docs:

• Markdown
• GitHub

How to contribute

• Using labels (may involve creating new labels exclusively for contributor use)
• Which files shouldn't be modified

How to use + understand the project

• Break down the documentation project folder structure and files (i.e. using a table)
• How to add to the side bar and nav bar
• How to run the project locally
• How we handle redirects
• How to access and modify code samples, incl. the location of SDK samples
• How we handle linting
  • What different errors mean +how to resolve them
• How we generate certain files, such as Postman file, openAPI, and API reference (if in the future this is generated based on an OpenAPI file)

Improving the style/organization/tone of contributions

• Style guide
• Tabs vs. spaces
• Character limits for page names + headers
• Conventions for referencing other parts of the docs
• Instructions about matching the tone of the documentation
• Any templates we use

[curquiza]

Thanks @dichotommy for the details

After conducting research and discussing it within the team, we determined that most open-source documentation sites do not use a CONTRIBUTING.md file. Instead, the common pattern is to explain how to contribute to a documentation site on the documentation site itself.

I'm curious about the examples you found out, if you are ok with sharing them 😊

You have to know people who get used to contribution expect a CONTRIBUTING.md -> this is the basis of opensource good practice. Adding explanations in the docs does not prevent adding a CONTRIBUTING.md file 😊 (+ modifying the current README). So I really would recommend adding a CONTRIBUTING additionnaly to what you planned.

Also a tips, with my contributor experience: the more you write guidelines, the less they read. Also, it's important not to afraid the contributors who are serious, want to help you and are discouraged by the text to read. Be careful not to put too much information in the contribution onboarding 🐣

And finally, I was wondering: when searching in the search bar, are we sure we want people to find the doc processes in the documentation? For me, the docs are not really the place for your processes, but this is only my opinion. Maybe we could prevent some pages from being indexed for examples?

[maryamsulemani97]

Hi 👋 Here are the examples we found:

• GitLab
• MongoDB
• TensorFlow
• matplotlib
• Medusa

[curquiza]

Thanks for sharing @maryamsulemani97 You will notice all of them (except matplotlib) have CONTRIBUTING.md and even redirect to them in their guidelines

[maryamsulemani97]

Sorry, I forgot to add this 🤦‍♀️ We could have a CONTRIBUTING.md file that we can keep short to avoid overwhelming users, as you mentioned and link to the docs where we can go into a lot more detail