Merge pull request #62 from themr0c/intro-enhancements

antora.yml

@@ -26,6 +26,11 @@ asciidoc:
     icons: font
     # for the project
     context: docs
+    ibmsg: IBM Style Guide
     repository-name: vale-at-red-hat
     repository-url: https://github.com/vale-at-red-hat/vale-at-red-hat
     repository-clone-url: [email protected]:vale-at-red-hat/vale-at-red-hat.git
+    ssg: Red Hat supplementary style guide for product documentation
+    ssg-url: https://redhat-documentation.github.io/supplementary-style-guide/
+    valedict: Custom Vale open-source dictionary for American English.
+    valedict-url: https://github.com/errata-ai/en_US-web

modules/end-user-guide/partials/con_glossary.adoc

@@ -6,24 +6,36 @@
 == Vale concepts
 
 `vale`::
-The Vale command-line tool.
+The link:https://docs.errata.ai/vale/about[Vale command-line tool] that brings code-like linting to prose.
 
 Rule::
-A YAML file defining a language issue, a proposed solution, and a link to more information.
+A YAML file defining:
++
+* a language issue, including spelling issues
+* a proposed solution
+* a link to more information.
 
 Style::
-A directory containing a collection of rules.
+A directory containing a collection of rules. You can choose to use a style as distributed by an upstream project, or include a copy in your project.
 
 Vocabulary::
-A directory containing lists of accepted and rejected words, applying to all styles. See xref:extending-the-vocabulary.adoc[].
+A directory in a project, containing lists of accepted and rejected words, applying to all styles. See xref:extending-the-vocabulary.adoc[].
 
 == Vale configuration files
 
-`.vale` directory:: 
-Contains a collection of Styles and Vocabularies.
+Styles directory:: 
+Contains a collection of Styles and Vocabulary. In this repository it is:
++
+----
+.vale/styles
+----
 
 `.vale.ini` configuration file:: 
-Tells Vale where to find the `.vale` directory and other important settings.
+It determines
++
+* The styles location
+* Patterns to match files to validate
+* 
 
 
 

modules/end-user-guide/partials/con_the-benefits-of-using-vale.adoc

@@ -3,23 +3,33 @@
 [id="con_the-benefits-of-using-vale_{context}"]
 = The benefits of using vale
 
-How does Vale help you improve your content quality and productivity?
+How does Vale help you improve your content quality and productivity?::
 
 * It helps you fix style issues right away before you create a PR
 * It improves peer reviews
 * It makes content more consistent
 * It makes content easier to localize
 * It makes content easier for users to understand
 
-The link:{repository-url}[{repository-name} repository] contains: 
+link:{repository-url}[The {repository-name} repository]:: 
 
-* The *RedHat* Vale style, containing language rules suitable for documentation in Open Source projects and mandatory for Red Hat products
-* The associated Vale configuration file
+Contains resources to validate language in documentation projects using Vale:
+
+* The _RedHat_ style for Vale
+* Vale configuration files
 * Documentation to start using Vale
 * Guidelines to define a Vale onboarding strategy in a project
-* Guidelines to contribute to the *RedHat* Style
+* Guidelines to contribute to the _RedHat_ Style
 * Guidelines to create a project specific Style or Vocabulary
 
+The _RedHat_ style for Vale::
+Contains language rules suitable for documentation in Open Source projects and mandatory for Red Hat products. These language rules originates from:
+
+* link:{ssg-url}[_{ssg}_]
+* Latest edition of the _{ibmsg}_
+* link:https://github.com/errata-ai/IBM[Vale-compatible implementation] of link:https://www.ibm.com/developerworks/library/styleguidelines/index.html[_IBM's Developer Editorial Style Guide_]
+* link:{valedict-url}[_{valedict}_]
+
 .Additional resources
 
 * xref:getting-started-with-vale.adoc[]