Skip to content

Commit

Permalink
adding do not use terms rule
Browse files Browse the repository at this point in the history
  • Loading branch information
aireilly committed Jul 28, 2023
1 parent 24ed372 commit 20a4f5d
Show file tree
Hide file tree
Showing 4 changed files with 67 additions and 0 deletions.
5 changes: 5 additions & 0 deletions .vale/fixtures/RedHat/DoNotUseTerms/.vale.ini
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
; Vale configuration file to test the `DoNotUseTerms` rule
StylesPath = ../../../styles
MinAlertLevel = suggestion
[*.adoc]
RedHat.DoNotUseTerms = YES
28 changes: 28 additions & 0 deletions .vale/fixtures/RedHat/DoNotUseTerms/testinvalid.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
comprised of
consume
consumed
could
daughterboard
destroy
dev
ecosystem
expose
foo
future-proof
in other words
in the event
kill
kilobyte
latest
new
out of the box
out-of-the-box
persist
please
vanilla
via
w/ something
w/o something
we
while
would
Empty file.
34 changes: 34 additions & 0 deletions .vale/styles/RedHat/DoNotUseTerms.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
extends: substitution
ignorecase: true
level: suggestion
link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/donotuseterms/
message: "%s"
swap:
# Start each error text with "Use/Do not use ..."
'w/ ': 'Do not use "w/". Spell out with.'
comprised of: 'Do not use "comprised of". Use consists of or composed of to describe parts of a whole (for example, "the library is composed of five books").'
consume[sd]?: 'Do not use "consume" when a simpler term such as use is possible. Consume is acceptable when it is part of the existing product terminology.'
could: 'Do not use "could" in the present tense to mean might or can. Use only in the past conditional form, for example, "files that could not be identified".'
daughterboard: 'Do not use "daughterboard". Use the specific name or function of the plug-in adapter that you are referring to.'
destroy: 'Do not use "destroy" to refer to the removal of an object from a database. Write specifically what happens to the object, such as deleting it from the database.'
dev: 'Do not use "dev" as a synonym for development or developer.'
ecosystem: 'Do not use "ecosystem" to mean a computer network environment. Use only to refer to a biological environment or to a business community of interacting organizations and individuals.'
expose: Do not use "expose" when a simpler term such as display or show is possible. Expose is acceptable when it is part of the existing product terminology.
foo: 'Do not use "foo". Developers sometimes use this term as technical jargon in code and as shorthand for fubar, an acronym of profanity in code. If you see this term in sample code, revise the example or do not publish it. Rewrite any text to omit the term.'
future-proof: Use "future-proof" with caution. Do not use the term in a statement about the benefits, characteristics, or performance of a Red Hat product or service.
in other words: 'Do not use "in other words". Use for example or that is. Ideally, state the original information clearly so that it does not require explanation.'
in the event: 'Do not use "in the event". Use in case, if, or when.'
kill: Do not use "kill" except when you are documenting a UNIX system, such as AIX. Use end or stop.
kilobytes?: 'Do not use "kilobyte". Use the abbreviation KB or kB, not the spelled-out form. If your audience needs to see the spelled-out form of an abbreviation, include the spelled-out form parenthetically on first use only, and use only the abbreviation in all other occurrences.'
latest: 'Do not use "latest" to describe products, functions, features, technologies, or standards when the term will become obsolete if another version is released.'
new: 'Do not use "new" to describe products, functions, features, technologies, or standards, other than in content such as release notes that are updated for each release.'
out of the box|out-of-the-box: 'Do not use "out of the box" or "out-of-the-box". Use text that is suitable for the context and the noun to which this adjective applies. For example, write applications that you can rapidly integrate into the system, items that are ready for immediate use, default settings, initial values, or built-in components.'
persist: 'Use "persist" only as an intransitive verb: "If you want your data to persist after the process ends…". Do not use as a transitive verb. In other words, don’t use persist with a direct object: "The applications persist data…".'
please: 'Do not use "please". Terms of politeness are superfluous, convey the wrong tone for technical material, and are not regarded the same way in all cultures.'
vanilla: 'Do not use "vanilla" to refer to something, such as a product or function, that is a basic variation or is not customized. For example, write "a package that is not customized", not "a vanilla package".'
via: 'Use "via" to refer to routing data, such as in "Messages are routed via SMTP". In other situations, try to replace via with one of the following synonyms: across, along, by, from, on, or through.'
w/o: 'Do not use "w/o". Spell out without.'
we: 'Do not use "we" to refer to Red Hat or to refer collectively to both the authors and the audience.'
while: 'Use "while" only to refer to a period of time. To avoid potential ambiguity, do not use the term as a synonym for although or though in documentation.'
would: 'Use "would" only to refer to an unfulfilled condition or hypothesis and to express the future in the past, for "The command was rejected because it would have resulted in the ClusterName attribute being blank." Do not use as an auxiliary verb, for example, "You would need administrator authority to create an app." Instead, use the present tense, for example "You need administrator authority to create an app."'

0 comments on commit 20a4f5d

Please sign in to comment.