errata-ai / Microsoft

A Vale-compatible implementation of the Microsoft Writing Style Guide.
https://github.com/errata-ai/vale
MIT License
85 stars 46 forks source link

Updated Terms.yml and Foreign.yml #50

Closed kayx23 closed 1 year ago

kayx23 commented 1 year ago

Updated term swapping suggestions in Terms.yml. Removed and updated tokens that are duplicated, unclear, or not meaningful. For details please see changed files.

Fixes #48

kayx23 commented 1 year ago

One of the removed swapping suggestion is bps (basis points). I don't think it makes sense to suggest against the use of the shorthand form bps.

jdkato commented 1 year ago

Please cite the style guide for removals or additions -- it's not about what you or I deem meaningful.

For example, the guide explicitly states to not use "alphanumerical" which you've removed.

kayx23 commented 1 year ago

Thanks for the resource. Weirdly interesting to find out that Drive C is recommended over C Drive...

I went through the relevant docs for my changes.

  1. For artificial intelligence: AI:

To refer to the technology itself, use AI for all audiences and in most content, including blogs, websites, and email. Don't spell out artificial intelligence. "

https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/ai-bot-terms

  1. For '(?:assembler|machine language)': assembly language:

https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/assembly-language

  1. For bps and bpp:

Didn't find any doc supporting if they should be in other forms. Did not even find what bpp stands for.

kayx23 commented 1 year ago

Also, any recommended way to add a link (or with any other way) to let new users know term rules here are defined based off the microsoft style guide a-z word lists?

I see reference could be provided using link:, such as link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/adapter

Perhaps we can add something like this with a comment saying rules for other terms could be found in the same guide?

jdkato commented 1 year ago

Also, any recommended way to add a link (or with any other way) to let new users know term rules here are defined based off the microsoft style guide a-z word lists?

I see reference could be provided using link:, such as link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/adapter

Perhaps we can add something like this with a comment saying rules for other terms could be found in the same guide?

👍

kayx23 commented 1 year ago

@jdkato updated a bit more. Ready for review!

jdkato commented 1 year ago

Looks good. Thanks!