From e629a2e29b0b734ed86e6cffd7c92289420eb946 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabrice=20Flore-Th=C3=A9bault?= Date: Thu, 21 Oct 2021 15:57:33 +0200 Subject: [PATCH] docs: introduction enhancements --- antora.yml | 5 ++++ .../end-user-guide/partials/con_glossary.adoc | 26 ++++++++++++++----- .../con_the-benefits-of-using-vale.adoc | 20 ++++++++++---- 3 files changed, 39 insertions(+), 12 deletions(-) diff --git a/antora.yml b/antora.yml index 900c90168..675543149 100644 --- a/antora.yml +++ b/antora.yml @@ -29,3 +29,8 @@ asciidoc: repository-name: studious-fortnight repository-url: https://github.com/rolfedh/studious-fortnight repository-clone-url: git@github.com:rolfedh/studious-fortnight.git + ibmsg: IBM Style Guide + 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 diff --git a/modules/end-user-guide/partials/con_glossary.adoc b/modules/end-user-guide/partials/con_glossary.adoc index 16dc4a965..846179492 100644 --- a/modules/end-user-guide/partials/con_glossary.adoc +++ b/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 +* diff --git a/modules/end-user-guide/partials/con_the-benefits-of-using-vale.adoc b/modules/end-user-guide/partials/con_the-benefits-of-using-vale.adoc index 7dd730ff6..ac56c779b 100644 --- a/modules/end-user-guide/partials/con_the-benefits-of-using-vale.adoc +++ b/modules/end-user-guide/partials/con_the-benefits-of-using-vale.adoc @@ -3,7 +3,7 @@ [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 @@ -11,15 +11,25 @@ How does Vale help you improve your content quality and productivity? * 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[]