Vale next steps

[maryamsulemani97]

https://github.com/meilisearch/documentation/pull/1646 adds basic rules to the docs. We will be updating these rules and adding new ones over time. The full list of current+possible rules can be found in Notion.

The next step is to fix the following current rules:

• [x] FirstPerson.yml

  • Possible solution: Update the message to something like: Avoid first-person pronouns such as '%s' unless writing FAQs"
  • Figure out how to ignore this rule for certain pages like FAQs, Telemetry, etc.

• [x] HeadingPunctuation.yml and Headings.yml

  • Both rules don't work for headings like 1. Click this and 1.2. Click here. #1776

Add new rules:

• [ ] ~~No capitals after colons in sentences~~
  • Too many exceptions
• [x] Decide max sentence length (most rules use 25-30)
  • Most of our “longer” (more than 25 words) sentences are between 27-30 words. The longest are ~42. We can start with a max sentence length of ~40 words and see how that goes. #1777
• [ ] Sound less condescending. See discussion here: https://github.com/meilisearch/documentation/pull/1662

Start working on:

• [ ] a list of words to replace to avoid wordy sentences (e.g., replace in order to with to)
• [x] a list of US vs British spelling so we follow US English #1775
• [ ] ~~consider if we need any readability metrics~~
  • Not very helpful, they just give you a number and you have to figure out what to fix

[dichotommy]

Once these steps have been achieved, and we've done sufficient iteration on the rules to be sure they will not create false positives, we will move to the final step: add Vale to our checks CI.

[maryamsulemani97]

To be done:

1. We currently have 28 warnings and 36 suggestions

• 4 warnings for using indexation instead of indexing
• 2 suggestions for the Oxford comma
  • The Oxford comma rule does not work as intended for complex sentences with many commas. This is also mentioned in the OxfordComma.yml file.
• 19 suggestions for the First person rule. Most of the pages that have this suggestion will be moved to the Developer hub
• 10 suggestions for using the semicolon. We will need to rewrite these sentences
• 5 suggestions for the Heading rule (use sentence-style capitalization). There are some headings where we don't follow this format:
  • "Meilisearch Documentation" in index.md
  • "Recommended: "Previous" and "Next" buttons" in learn/advanced/pagination.md
• 24 warnings for typos; most of these are intentional

You will only get all these warnings and suggestions if you run vale . locally on the docs. The Vale action only shows an error/warning/suggestion if you break any of the rules in the content you added or edited.

2. Update sentences to sound less condescending
3. A list of words to replace to avoid wordy sentences (e.g., replace in order to with to)

• This isn't a high priority as we haven't identified such phrases yet

[maryamsulemani97]

Closing this for https://github.com/meilisearch/documentation/issues/1939