[Feature]: Consider switching to Vale linter

[peterjunpark]

Suggestion Description

Vale is an open-source command-line tool to enforce editorial style. I believe updating our docs linting CI to use Vale could significantly improve the workflow for docs contributors and the overall writing quality/consistency of the docs. See https://vale.sh/docs/. (and blogs...)

Some further reading: https://www.datadoghq.com/blog/engineering/how-we-use-vale-to-improve-our-documentation-editing-process/

Editorial style

Google Developer Documentation style guide

The ROCm docs are aligned with the Google Developer Documentation Style Guide. Vale has built-in support for Google style guide rules through https://vale.sh/hub/google/, allowing us to enforce these rules automatically. Additional editorial style guides are available and can be easily integrated through other add-ons on at https://vale.sh/hub/.

Custom editorial rules can also be created to address ROCm-specific stylistic preferences, enhancing the clarity and consistency of our technical language.

This would simplify and speed up documentation reviews.

Blocking/non-blocking style violations

Vale’s configurable rules let us categorize certain violations as blocking (key terminology errors, etc) to prevent merging, while others can be non-blocking, serving only as style suggestions. This allows a balanced approach to enforcing editorial standards without causing unnecessary interruptions.

Example use case: trademark symbol

We should have a trademark symbol on every first instance of an AMD product name on each page. This (and other custom rules) are enforceable using https://vale.sh/explorer/trademarks/.

Markup formats

Vale supports rST and MD out-of-the-box. We can easily add custom rules for Sphinx directives if needed. We can also lint source code comments for API docs generated by Doxygen.

Wordlist

See https://vale.sh/docs/topics/vocab/.

GitHub action

https://github.com/errata-ai/vale-action

Editor integration

Vale also has in-editor support, providing real-time linting with red underlines to highlight style violations as contributors write. This promotes consistency from the start of the writing process.

Operating System

No response

GPU

No response

ROCm Component

No response

[peterjunpark]

@alexxu-amd @samjwu @lpaoletti @yhuiYH Do you think this is worth looking into?

[lpaoletti]

I don't think we're ready to move there.
This is not a priority compared to the other changes we need to make.

[yhuiYH]

I think it's worth looking in to for sure. I've been wanting to enable spell checks on all repos. Link checking linter too, if we have one to use.

I haven't looked too closely, but can we just add vale linter to run in parallel with our current linters? To evaluate?

[lpaoletti]

We used this at my previous company - it works well. But the initial hit can be overwhelming.

[samjwu]

setting up a GA just to run seems to be simple with https://github.com/errata-ai/vale-action

configuration of custom rules for things like language style I expect would take the longest time investment, and would have to be headed by the writing team