errata-ai / ibm Goto Github PK

Comment taken from here - testthedocs/vale-styles#7 (comment)

There are a group of people interested in contributing to this style:

@themr0c, @rkratky, @MichalMaler, @boczkowska, @robin-owen @gaurav-nelson and myself. Not sure if it's easier for you to add us as contributors or just accept PRs?

1. Terms.yml file includes all words marked as do not use. (❗ in the IBM guide) (Error)
2. Checkusage.yml file includes all terms used with caution (⚠️ in the IBM guide)(Warning)

These files do not include terms marked as correct usage (✅ in the IBM guide), Maybe we can mark them as suggestions ? Thoughts?

To save flooding the repo with issues, this is a big issue a check list people can break out as they go:

(Naturally this is what vale can check, there are other rules in the guide that are kind of impossible right now)

• Use second person: A variant of this rule might help.
• Prefer shorter words: Examples here, here and here, probably way more.
• Use active voice: Use the write-good rule
• Start a sentence that contains a conditional phrase with the conditional phrase so that the reader can skip the rest of the sentence with confidence if the condition doesn't apply.: Not sure
• Aim for economical expression: Examples here, here, here, here
• Avoid abbreviations: Somewhat industry dependent, but examples to build upon here and here. Specifics for IBM are here and also here.
• Capitalization: We can only really check sentence case for headings, see example here.
• GUI elements terminology: Source in guide, we could possibly set up a terms style check like here.
• Hyphenation: Source in guide. Could be a check for this, might give too many false positives.
• Lists: Source in guide. I'm not sure if this is something Vale can check, or should check as it's more about structure than grammar. Maybe some of the lists rules we can replicate.
• Punctuation:
  • Lead-in punctuation: Not sure how we can check
  • Exclamation marks: Example here.
  • Do not use slashes as substitutes for words (and, or): Thought I saw a rule for this but maybe not, should be possible to replicate.
  • Comma in a series: Oxford comma basically, an example here.
  • Comma between an independent and a dependent clause: Not sure how we do this.
  • Ellipses: Example here.
  • Long dashes: Examples here and here.
• Structure: Not too many we can check, but here's some:
  • Sentence length: Example here.
  • Abstract: A lot in this rule replicates others, but there's one loose one about the present tense, an example for that is here.
  • Word usage: There's a lot in this rule, I think many are handled by other rules we can add too.

Might have missed some details, feel free to add too. When you tackle one, strike it through, create an issue and link to it 👍🚀