From 4943fe22b728817dd83cded6d2bf2e3e2eab35b5 Mon Sep 17 00:00:00 2001 From: aireilly Date: Mon, 28 Aug 2023 10:02:00 +0100 Subject: [PATCH] new ProductCentricWriting rule --- .../fixtures/RedHat/ProductCentricWriting/.vale.ini | 5 +++++ .../RedHat/ProductCentricWriting/testinvalid.adoc | 4 ++++ .../RedHat/ProductCentricWriting/testvalid.adoc | 0 .vale/styles/RedHat/ProductCentricWriting.yml | 13 +++++++++++++ modules/reference-guide/nav.adoc | 7 ++++--- modules/reference-guide/pages/pascalcamelcase.adoc | 2 +- modules/reference-guide/pages/passivevoice.adoc | 2 +- .../pages/productcentricwriting.adoc | 11 +++++++++++ 8 files changed, 39 insertions(+), 5 deletions(-) create mode 100644 .vale/fixtures/RedHat/ProductCentricWriting/.vale.ini create mode 100644 .vale/fixtures/RedHat/ProductCentricWriting/testinvalid.adoc create mode 100644 .vale/fixtures/RedHat/ProductCentricWriting/testvalid.adoc create mode 100644 .vale/styles/RedHat/ProductCentricWriting.yml create mode 100644 modules/reference-guide/pages/productcentricwriting.adoc diff --git a/.vale/fixtures/RedHat/ProductCentricWriting/.vale.ini b/.vale/fixtures/RedHat/ProductCentricWriting/.vale.ini new file mode 100644 index 000000000..7d393ea67 --- /dev/null +++ b/.vale/fixtures/RedHat/ProductCentricWriting/.vale.ini @@ -0,0 +1,5 @@ +; Vale configuration file to test the `ProductCentricWriting` rule +StylesPath = ../../../styles +MinAlertLevel = suggestion +[*.adoc] +RedHat.ProductCentricWriting = YES diff --git a/.vale/fixtures/RedHat/ProductCentricWriting/testinvalid.adoc b/.vale/fixtures/RedHat/ProductCentricWriting/testinvalid.adoc new file mode 100644 index 000000000..f82ab678d --- /dev/null +++ b/.vale/fixtures/RedHat/ProductCentricWriting/testinvalid.adoc @@ -0,0 +1,4 @@ +OpenShift allows customers to use a Kubernetes Network Policy to create microsegmentation between deployed application services on the cluster. +The `monitoring-rules-edit` rule permits you to create and silence alerts in the *Developer* perspective in the web console. +The `must-gather` tool enables the user to collect diagnostic information about your cluster. +LoadBalancer lets users assign an external load balancer to an associated service API object in your {product-title} cluster. diff --git a/.vale/fixtures/RedHat/ProductCentricWriting/testvalid.adoc b/.vale/fixtures/RedHat/ProductCentricWriting/testvalid.adoc new file mode 100644 index 000000000..e69de29bb diff --git a/.vale/styles/RedHat/ProductCentricWriting.yml b/.vale/styles/RedHat/ProductCentricWriting.yml new file mode 100644 index 000000000..c404adac9 --- /dev/null +++ b/.vale/styles/RedHat/ProductCentricWriting.yml @@ -0,0 +1,13 @@ +--- +extends: substitution +ignorecase: true +level: suggestion +link: https://redhat-documentation.github.io/vale-at-red-hat/docs/main/reference-guide/productcentricwriting/ +message: "%s" +swap: + # Start each error message with "Do not use ..." + # Error messages must be single quoted. + 'allows(?: you| customers| the customer| the user| users)': 'Do not use "allows" to grant abilities to inanimate objects, as in "the product allows you to…". Whenever possible, use a direct, user-focused alternative.' + 'enables(?: you| customers| the customer| the user| users)': 'Do not use "enables" to grant abilities to inanimate objects, as in "the product enables you to…". Whenever possible, use a direct, user-focused alternative.' + 'lets(?: you| customers| the customer| the user| users)': 'Do not use "lets" to grant abilities to inanimate objects, as in "the product lets you…". Whenever possible, use a direct, user-focused alternative.' + 'permits(?: you| customers| the customer| the user| users)': 'Do not use "permits" to grant abilities to inanimate objects, unless the object is a type of authorization that does grant abilities.' diff --git a/modules/reference-guide/nav.adoc b/modules/reference-guide/nav.adoc index 9d3fec94b..c60677d59 100644 --- a/modules/reference-guide/nav.adoc +++ b/modules/reference-guide/nav.adoc @@ -9,11 +9,10 @@ * xref:ellipses.adoc[] * xref:headingpunctuation.adoc[] * xref:headings.adoc[] -//* xref:images.adoc[] -//* xref:links.adoc[] * xref:oxfordcomma.adoc[] * xref:pascalcamelcase.adoc[] * xref:passivevoice.adoc[] +* xref:productcentricwriting.adoc[] * xref:readabilitygrade.adoc[] * xref:releasenotes.adoc[] * xref:repeatedwords.adoc[] @@ -28,4 +27,6 @@ * xref:termssuggestions.adoc[] * xref:termswarnings.adoc[] * xref:usage.adoc[] -* xref:userreplacedvalues.adoc[] \ No newline at end of file +* xref:userreplacedvalues.adoc[] +//* xref:images.adoc[] +//* xref:links.adoc[] diff --git a/modules/reference-guide/pages/pascalcamelcase.adoc b/modules/reference-guide/pages/pascalcamelcase.adoc index 2a5575eef..2b44a01ed 100644 --- a/modules/reference-guide/pages/pascalcamelcase.adoc +++ b/modules/reference-guide/pages/pascalcamelcase.adoc @@ -1,4 +1,4 @@ -:navtitle: PascalCamelCase +:navtitle: Pascal and camel case :keywords: reference, rule, PascalCamelCase = Pascal case and Camel case diff --git a/modules/reference-guide/pages/passivevoice.adoc b/modules/reference-guide/pages/passivevoice.adoc index e795daf49..dfdf72631 100644 --- a/modules/reference-guide/pages/passivevoice.adoc +++ b/modules/reference-guide/pages/passivevoice.adoc @@ -1,4 +1,4 @@ -:navtitle: PassiveVoice +:navtitle: Passive voice :keywords: reference, rule, PassiveVoice = Passive Voice diff --git a/modules/reference-guide/pages/productcentricwriting.adoc b/modules/reference-guide/pages/productcentricwriting.adoc new file mode 100644 index 000000000..f396b307d --- /dev/null +++ b/modules/reference-guide/pages/productcentricwriting.adoc @@ -0,0 +1,11 @@ +:navtitle: Product-centric writing +:keywords: product-centric, writing + += Product-centric writing + +Do not use product-centric writing to grant abilities to inanimate objects. Where possible, make the user the subject of the sentence. + +.Additional resources + +* link:{ibmsg-url-print}[{ibmsg-print} - Conversational style, p. 19] +* link:{ibmsg-url}?topic=medium-conversational-style[{ibmsg} - Conversational style]