search

commercetools / commercetools-docs-kit

Tools and components for developing Documentation websites 🛠
https://docs-kit.commercetools.vercel.app
MIT License
18 stars 5 forks source link

Writing Style Improvements #437

Closed nkuehn closed 2 years ago

nkuehn commented 4 years ago

this issue serves as a place to collect improvement ideas for the writing style linter rules. Please add ideas as comments

Implementation will be done periodically.

nkuehn commented 4 years ago

seen: NodeJS, Nodejs, node.js, node (the latter can't be disambiguated but is here for completeness)

should be: Node.js

reference: https://nodejs.org/en/

nkuehn commented 4 years ago

seen:

should be allowed.

Rule: Acronyms.

nkuehn commented 4 years ago

seen: .NET (correct, but the linter thinks we forgot a space after the end of a sentence)

should be allowed

nkuehn commented 4 years ago

For awareness (not seen yet): We can warn or block race and slavery related metaphors technical language as it was brought up by various open source projects. For example

It's covered in Google's writing style that we base on but not checked in this automated checker. https://developers.google.com/style/inclusive-documentation#features-and-users

nkuehn commented 4 years ago

@stmeissner found this in a release note:

nkuehn commented 4 years ago

maybe already covered in our weasel words but occurred in a recent docs PR: "upgraders", like absolute, utterly, overly

nkuehn commented 4 years ago

Here's a repository with a lot of various style guide rules for inspiration to pick things from: https://github.com/testthedocs/vale-styles

nkuehn commented 4 years ago

deactivate "Vale.spelling" rule - I am adding suggestions to the configuration of the VSCode workspace, but the spelling is dominating the output and is not of good quality. The VScode spellright plugin does a better job by using the operating system spell checker.

stmeissner commented 4 years ago

Currently we have no guideline for abbreviations of high numbers. like 1 million. In a PR I found 1M as acronym, but this is not covered by the Google Style Guide. One option is to forbid such abbreviations at all since they are rather used as unit of measurements for which we have clearer rules, e.g. 1 MB for one megabyte.

adinakleine commented 4 years ago

Currently we have no guideline for abbreviations of high numbers. like 1 million. In a PR I found 1M as acronym, but this is not covered by the Google Style Guide. One option is to forbid such abbreviations at all since they are rather used as unit of measurements for which we have clearer rules, e.g. 1 MB for one megabyte.

I like the idea of eliminating unnecessary abbreviations like this. 👍

nkuehn commented 4 years ago

In a PR I found 1M as acronym, but this is not covered by the [Google Style Guide]

Please see https://developers.google.com/style/units-of-measure , it's "implicitly covered" as the google style explicitly allows "5k" (small "k" for thousands) as an exemption, but not "3m" for millions. The question is technically not about units as measure but they seem to cover it on that page (i guess because it's usually coming up alongside with "KB" vs. "kilobyte" vs. "Kb" etc.)

adinakleine commented 4 years ago

For awareness (not seen yet): We can warn or block race and slavery related metaphors technical language as it was brought up by various open source projects. For example

  • whitelist(ed) -> allowed, good, ...
  • blackliste(ed) -> disallowed, forbidden, ...
  • master
  • slave
  • native (feature)
  • ...

It's covered in Google's writing style that we base on but not checked in this automated checker. https://developers.google.com/style/inclusive-documentation#features-and-users

FYI: There is already an issue for discussion in the fe-chapter-notes repository.

nkuehn commented 4 years ago

commercetools set terms:

adinakleine commented 4 years ago

commercetools set terms:

nkuehn commented 4 years ago

"CORS" - spelling it out does not explain it better.

nkuehn commented 4 years ago

The Vale VSCode plugin now supports configuring it to show "suggestion" level rules in the editor without running them on GitHub too (and annoying everybody).

I tried it, its nice for some things but the current state of the rules show enormous numbers of suggestions of whom most that are not a fit for us are from the "write-good" ruleset. I think it would be good to pick a few purely stylistic rules and show them to authors as suggestions, but the current state makes the editor UI very annoying.

stmeissner commented 4 years ago

In the Docs Smoke Test we have the term "chapter" in the left hand navigation, but the style checker currently reports a warning about this: Use 'document, page, or section' instead of 'chapter' (case insensitive).

nkuehn commented 3 years ago

"VAT" acronym for value added tax can be allowed in a commerce environment.

adinakleine commented 3 years ago

"VAT" acronym for value added tax can be allowed in a commerce environment.

Added to acronyms.yml in PR #840

adinakleine commented 3 years ago

seen:

  • "USA" is forbidden
  • "NPM" is forbidden (the node package manager, but nobody spells it out in real life)

should be allowed.

Rule: Acronyms.

Added to acronyms.yml in PR #840

nkuehn commented 2 years ago

Notes from working through the rules with @timonrey :