studious-fortnight

This repo helps tech writers at Red Hat get up and running with Vale. It serves as the starting point for the Vale Community of Practice at Red Hat.

What does using Vale look like?

As a technical writer, you typically run vale on the command-line against a content file:

[rdlugyhe@rdlugyhe ~]$ cd openshift-docs/logging/troubleshooting/
[rdlugyhe@rdlugyhe troubleshooting]$ vale cluster-logging-troubleshooting-for-critical-alerts.adoc

The resulting command output gives you a list of suggestions, warnings, and errors based on customizable styles and vocabularies.

 238:27   error       Did you really mean             Vale.Spelling       
                      'rebalancing'?                                      
 244:6    suggestion  Verify your use of 'there       IBM.Usage           
                      are' with the word usage                            
                      guidelines.                                         
 244:38   warning     Consider using 'available'      CheDocs.CommonTerms
                      instead of 'present'

Understanding the vale command output example:

• The first column is the line and character number of the issue, such as 244:6.
• The second column is the type of issue, such as error, suggestion, or warning.
• The third column is the style prompt: Verify your use of 'there are'
• The fourth column is the source of the rule, such as IBM.Usage

As a writer, you review output, decide which issues are valid, and update your contents accordingly.

What if the command output from Vale is wrong? For example, what if the word rebalancing appears in Red Hat's products (it does) and it's also dictionary word? Why is it showing up as an error?

Good question. It's probably missing from the Vale.Spelling dictionary. The solution is for one of us to add it the list of allowed words. This brings us to...

How can you contribute to this project?

You can help by doing any of the following:

• Use Vale with the style rules from this studious-fornight repo.
• Report issues and request enhancements.
• Coding new style rules.

To become a contributor, check out this contributor's guide

What are the important parts of this repo?

• The .vale directory contains a collection of styles, which are collections of rules that are based on the style guides we use at Red Hat. Members of Eclipse Che documentation project team have been refining and using these styles for over a year.

• The .vale.ini configuration file that tells Vale where to find the .vale directory and other important settings.

How do you get started?

1. For Linux and Mac I suggest installing the Homebrew package manager. It makes installing and updating software like Vale easier. (I'll also mention how to install Vale without using homebrew later on.)

2. Install the Vale command line tool on your workstation.

NOTE: On the Vale site, click the tab for your operating system.

1. Use git clone to copy this repo, studious-fortnight, to your local machine. For example:

$ cd ~
$ git clone [email protected]:rolfedh/studious-fortnight.git

1. Copy the .vale.ini file and .vale directory from the studious-fortnight directory to the directory where you keep your documentation projects.

For example:

$ cp -r ./studious-fortnight/.vale* ./

1. Run the vale command on one of your content files. For example:

$ cd openshift-docs
$ vale modules/<filename>.adoc

1. Review the vale output and use some of it update your content file.

2. Re-run the same vale command to see the new results.

Caveat: The styles are not perfect and not complete. Don't be discouraged by the output from vale. Simply review the output and choose what's useful to you. We're working on making them better.

The benefits of using Vale

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 is easier to for users to understand.

Vale styles and rules

• A style is a simple directory that contains a collection of rules.
• A rule is a .yml file that defines the issue, the solution, and other information.
• You can use a style as-is, or you customize the rules it contains to fit your needs.
• This repo includes

Optional next steps

• Install VS Code and the Vale plugin for VS Code.
• Add Vale to your docs continuous integration (CI) service.
• Add Vale to your GitHub actions.

Related topics

• Troubleshooting common errors.
• Blog posts for Studious-Fortnight
• Rolfe's "Vale notes" blog posts

How to get involved, get help, and contribute

• Join the Slack channel, #vale-at-red-hat, in the CoreOS workspace.
• To report a bug in this repo or request an enhancement, create an issue.
• To show appreciation and support for Joseph Kato's work on Vale, consider making a donation.