[Docs] Fix merge errors / start vale checking in docs

[stichbury]

Description

Now ready for review. Sorry it's so large, it's because I have touched most of the docs pages at a superficial level to remove a few common issues that Vale is set to eliminate:

• Remove e.g. and replace with "for example"
• Remove "please" as unnecessarily wordy
• Remove "simple" and "just" as potentially making the user feel bad
• Replace some commonly used complex terms like "provide" with "give" and so on
• Add some line spacing to stop code sections from being dragged into Vale check
• Fix some link issues (break the build rather than Vale)

This PR also turns Vale on to run across all markdown in the /docs folders (thanks to @huong-li-nguyen).

Screenshot

Notice

• I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

  • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
  • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
  • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
  • I have not referenced individuals, products or companies in any commits, directly or indirectly.
  • I have not added data or restricted code in any commits, directly or indirectly.

[huong-li-nguyen]

I've just pushed a change 👍 From some of the threads I've quickly read e.g. this one, it seems like vale works the other way around. Instead of ignoring folders, you have to specify which ones you want to lint.

To test it, I just added "werkzeug" in the vizro-core or vizro-ai pages/docs/*.md files and then checked if vale was raising it and it did, but please double-check.

The docs build is currently still failing because of some broken links - not sure if these are false positives?

[huong-li-nguyen]

Hey @stichbury - LGTM in general! Thanks for tidying 🧹

I've noticed a couple other merge conflicts which I pointed out. Some of the rephrases sound a bit odd to me now, but it might just be because I am not a native speaker 😄 Especially the replacements from "provide" to "pass" sound a bit off, because it now says "pass with ..." and "pass to" sounds more correct to me? Anyways, I've commented on the relevant sections. So if relevant please take a look, if not, then feel free to ignore :)

[huong-li-nguyen]

LGTM 👍 Just have some minor comments, but from my side it's good to go 🚀

[maxschulz-COL]

Had a quick scan through - looks generally good 💪

Main question: is there a guidance when we must turn vale off?

Some things I noticed:

• e.g. into for example -> is this not too long?

[petar-qb]

After searching the vizro-core/docs files and some keywords I found the following:

• some forms of e.g. in: graph.md - 19, why-vizro.md - 100, why-vizro.md - 107, assets.md - 102, run.md - 48.
• etc in:cotributing.md - 111, why-vizro - 69, custom-components.md - several places,
• some form of i.e. - Nowhere.

Also in vizro-ai/docs I found the following:

• e.g.and etc in: safeguard.md 75, 76,

I don't know if we should strictly get rid of them. However, here's a little warning in case it helps 😄.

[stichbury]

Some things I noticed:

• e.g. into for example -> is this not too long?

Good question! In some cases, I removed the "e.g." and didn't replace with "for example" because it does make it wordy, but in others, it is useful to spell out that it's just one of many options/examples. We are familiar with e.g. but not everyone is, so technical writing tends to spell it out for clarity. It's one of those things that some like, some don't (and someone in the team uses it a lot!), so I do apologise if you fall on the other side of the rule for this one!

[stichbury]

After searching the vizro-core/docs files and some keywords I found the following:

• some forms of e.g. in: graph.md - 19, why-vizro.md - 100, why-vizro.md - 107, assets.md - 102, run.md - 48.
• etc in:cotributing.md - 111, why-vizro - 69, custom-components.md - several places,
• some form of i.e. - Nowhere.

Also in vizro-ai/docs I found the following:

• e.g.and etc in: safeguard.md 75, 76,

I don't need Vale with @petar-qb doing the checking :) Thanks for the spot!

Some may be excluded because I've turned Vale off on docs with official type text like the safeguarding page. I'll look into why others haven't been flagged and fix them all for consistency. Thanks @petar-qb !