Clarifying docs

rohennes · Apr 17, 2024 · ee0e899 · ee0e899
1 parent d1c0888
commit ee0e899
Show file tree

Hide file tree

Showing 4 changed files with 88 additions and 73 deletions.
diff --git a/modules/user-guide/nav.adoc b/modules/user-guide/nav.adoc
@@ -2,6 +2,7 @@
 
 * xref:introduction.adoc[]
 * xref:installing-vale-cli.adoc[]
+* xref:installing-redhat-style-for-vale.adoc[]
 * xref:analyze-with-vale.adoc[]
 ** xref:using-vale-app.adoc[]
 ** xref:using-vale-cli.adoc[]

diff --git a/modules/user-guide/pages/installing-redhat-style-for-vale.adoc b/modules/user-guide/pages/installing-redhat-style-for-vale.adoc
@@ -0,0 +1,74 @@
+// Metadata for Antora
+:navtitle: Installing the RedHat style
+:keywords: installing-redhat-style-for-vale, antora
+:description: Installing the Red Hat style for Vale
+// End of metadata for Antora
+:_module-type: CONCEPT
+[id="installing-redhat-style-for-vale"]
+= Installing the Red Hat style for Vale globally
+
+You can install the `RedHat` style for Vale globally.
+
+[IMPORTANT]
+====
+Some product documentation repositories, such as `openshift-docs`, have an existing `.vale.ini` file.
+When you run `vale` on content files in the repository directory, the `<repository>/.vale.ini` file overrides the `$HOME/.vale.ini` file. For more information, see link:https://vale.sh/docs/topics/config[Vale configuration reference].
+
+Run `vale sync` in your project directory to download the Vale rules relative to that project directory.
+====
+
+.Procedure
+
+. To use Vale with the `RedHat` package system-wide, create the following `.vale.ini` configuration file in your `$HOME` directory.
++
+.Example .vale.ini
+[source,ini]
+----
+include::example$vale.ini[]
+----
+
+. Sync the `RedHat` package to your computer.
++
+[source,console]
+----
+$ vale sync
+----
++
+.Example output
+[source,terminal]
+----
+$ vale sync
+ SUCCESS  Downloaded package 'RedHat'
+Downloading packages [1/1]
+----
++
+[TIP]
+To get the latest updates, run `vale sync` regularly.
+
+.Verification
+
+. Run `vale` against a source file:
++
+[source,console,subs="+quotes,+attributes"]
+----
+$ cd __<project_directory>__
+$ vale __<filename>__
+----
++
+.Example output
+[source,terminal]
+----
+$ vale modules/ztp-creating-the-site-secrets.adoc
+
+ modules/ztp-creating-the-site-secrets.adoc
+ 10:222  error       Use 'Assisted Installer'        Vale.Terms
+                     instead of 'assisted
+                     installer'.
+ 14:13   suggestion  'are referenced' is passive     RedHat.PassiveVoice
+                     voice. In general, use active
+                     voice. Consult the style guide
+                     for acceptable use of passive
+                     voice.
+
+✖ 2 errors, 0 warnings and 1 suggestion in 1 file.
+----
diff --git a/modules/user-guide/pages/installing-vale-cli.adoc b/modules/user-guide/pages/installing-vale-cli.adoc
@@ -5,19 +5,14 @@
 :page-aliases: end-user-guide:using-vale-cli.adoc, installing-vale-cli-from-zip.adoc
 // End of metadata for Antora
 [id="proc_installing-vale-cli"]
-= Installing Vale and the RedHat package
+= Installing Vale
 
-Install the Vale linter and the `RedHat` package to automate reviewing content for style and structure.
+Install the Vale linter to begin reviewing content for style and structure.
 
 [IMPORTANT]
 ====
-Vale v3 introduced a breaking change for the Vale vocabulary folder location.
-For Vale v3+, if you use a vocabulary with your project, ensure that the vocabulary folder matches this folder structure:
-
-[source,terminal]
-----
-.vale/styles/config/vocabularies/<project_vocab_folder>
-----
+If you are working in an established project that has already implemented Vale, you do not need to create a new `vale.ini`.
+The project will already have a `vale.ini` configuration.
 ====
 
 .Prerequisites
@@ -58,65 +53,6 @@ $ which vale
 [NOTE]
 For other operating systems, see link:https://vale.sh/docs/vale-cli/installation/[Installing Vale].
 
-. To use Vale with the `RedHat` package system-wide, create the following `.vale.ini` configuration file in your `$HOME` directory.
-+
-.Example .vale.ini
-[source,ini]
-----
-include::example$vale.ini[]
-----
-+
-[TIP]
-====
-Some product documentation repositories, such as `openshift-docs`, have a  `.vale.ini` file. When you run `vale` on content files in the repository directory, the `<repository>/.vale.ini` file overrides the `$HOME/.vale.ini` file. For more information, see link:https://vale.sh/docs/topics/config[Vale configuration reference].
-====
-
-. Download the `RedHat` package to your computer.
-+
-[source,console]
-----
-$ vale sync
-----
-+
-.Example output
-[source,terminal]
-----
-$ vale sync
- SUCCESS  Downloaded package 'RedHat'
-Downloading packages [1/1]
-----
-+
-[TIP]
-To get the latest updates, run `vale sync` regularly.
-
-.Verification
-
-. Run `vale` against a source file:
-+
-[source,console,subs="+quotes,+attributes"]
-----
-$ cd __<project_directory>__
-$ vale __<filename>__
-----
-+
-.Example output
-[source,terminal]
-----
-$ vale modules/ztp-creating-the-site-secrets.adoc
-
- modules/ztp-creating-the-site-secrets.adoc
- 10:222  error       Use 'Assisted Installer'        Vale.Terms
-                     instead of 'assisted
-                     installer'.
- 14:13   suggestion  'are referenced' is passive     RedHat.PassiveVoice
-                     voice. In general, use active
-                     voice. Consult the style guide
-                     for acceptable use of passive
-                     voice.
-
-✖ 2 errors, 0 warnings and 1 suggestion in 1 file.
-----
-
 .Additional resources
 * xref:understanding-vale-output.adoc[]
 * xref:defining-a-vale-onboarding-strategy.adoc[]

diff --git a/modules/user-guide/pages/redhat-style-for-vale.adoc b/modules/user-guide/pages/redhat-style-for-vale.adoc
@@ -15,18 +15,22 @@ The `RedHat` style for Vale consists of language rules suitable for documentatio
 * link:https://github.com/errata-ai/IBM[Vale-compatible implementation] of link:https://www.ibm.com/developerworks/library/styleguidelines/index.html[_IBM Developer Editorial Style Guide_]
 * link:{valedict-url}[_{valedict}_]
 
-The xref:contributor-guide:vale-at-red-hat-repository.adoc[] contains the `RedHat` style in the following directory:
+[IMPORTANT]
+====
+Vale v3 introduced a breaking change for the Vale vocabulary folder location.
+For Vale v3+, if you use a vocabulary with your project, ensure that the vocabulary folder matches this folder structure:
 
+[source,terminal]
 ----
-.vale/styles/RedHat
+.vale/styles/config/vocabularies/<project_vocab_folder>
 ----
 
+For more information see, link:https://vale.sh/docs/topics/vocab/[Vocabularies].
+====
+
 [role="_additional-resources"]
 .Additional resources
 * xref:installing-vale-cli.adoc[]
 * xref:using-vale-in-the-ide.adoc[]
 * xref:using-vale-github-action.adoc[]
 * xref:adding-vale-configuration-to-a-project.adoc[]
-
-
-