devportal icon indicating copy to clipboard operation
devportal copied to clipboard

Automatically generate rules to check capitalisation of "business nouns"

Open TibsAtWork opened this issue 2 years ago • 0 comments

Note: this depends on https://github.com/aiven/devportal/issues/1126

"business nouns" are company names, major products and so on.

In https://github.com/aiven/devportal/issues/1126 I propose splitting them out into a separate dictionary.

Doing so would enable the automatic generation of rules for catching mistakes in capitalising them.

At the moment, the file .github/vale/styles/Aiven/common_replacements.yml has such rules for some names (for instance, datadog -> Datadog and clickhouse -> ClickHouse) but not for others (for instance, GitHub). Having a separate file would make it easy to (periodically) generate a companion style file for just this purpose.

For the GitHub example, at the moment if you type github, you just get told that word isn't recognised, which is not particularly helpful, but adding every word we want to catch like that, by hand, is onerous.


What about if a "business noun" is also a common word? That is, there is a word businessnoun and a company called BusinessNoun.

Well, if the word businessnoun is in the dictionary, then BusinessNoun will be treated as an acceptable spelling of that, so in many cases that's all we need. We'd have to get into context to do any better, and there are limits to what we can (easily) do with a static linting tool.

If we never use the word businessnoun, then we might consider a rule to ensure use of BusinessNoun, which we can do with a specific "common replacements" rule, without need to add a new dictionary word. In such a case, I'd put a comment in the rule file explaining what was going on (see how we do so for the flick -> flink rule, for instance - we reckon we're unlikely to use the word flick in our docs, so it would be a typo).

TibsAtWork avatar Jul 07 '22 10:07 TibsAtWork