How we use Vale to enforce better writing in docs and beyond

Here at Spectro Cloud, we spend a lot of time and effort improving our product and ensuring our customers have a positive experience with it. We view documentation as a critical component of the product, so we pay significant attention to it. 

In previous articles, we have shed some light on the innovation and efforts spearheaded by our documentation and education team. In the last two years, the team has focused extensively on the writing quality of our documentation. Part of this effort to improve the writing quality is building a strong foundation around best writing practices and staffing the team with highly technical and proficient writers. 

However, despite amassing top-tier writing talent, we are prone to simple mistakes like everyone else. We also welcome and encourage non-documentation team members to contribute to the documentation and regularly receive contributions. To help all of us mitigate common slip-ups, such as misspellings, not adhering to our style guide, and so on, we leverage the open-source tool Vale.sh.

In this blog, we’d like to share why we use Vale, how we use it, how you can benefit from using Vale, and the steps we are taking to support the project.  

What is Vale?

Vale calls itself a ‘linter for prose’. It’s a Command Line Terminal (CLI) tool that can help teams and organizations programmatically enforce writing standards and rules. You can define rules that enforce a style guide and catch deviations that may slip through a human review process. The ability to aid the review process is truly what makes Vale an asset for any documentation team or teams that publish content. 

To better understand Vale and how it works, take a peek at the following rule. 

# Copyright (c) Spectro Cloud
# SPDX-License-Identifier: Apache-2.0

extends: existence
message: Using '%s' may come across as condescending.
link: https://spectrocloud.atlassian.net/wiki/spaces/DE/pages/1765933057/Spectro+Cloud+Internal+Style+Guide#Simplicity-Assumption
level: error
ignorecase: true
tokens:
  - obvious
  - obviously
  - simple
  - simply
  - easy
  - easily
  - of course
  - clearly
  - everyone knows
  - common sense
  - common knowledge

The rule checks for the existence of sayings that may create an assumption that an action is simple. We avoid language like this as our product is used by professionals at different skill levels. What may be simple for one person may be more challenging for another. So, to avoid demoralizing readers, we avoid unnecessary assumptions. 

Vale can consume various documentation formats, such as Markdown, HTML, AsciiDoc, and more. You can also use Vale to check comments for various programming languages. Using the rule example from earlier, assume a markdown file has the following sentence.

Simply create a new Webpack configuration and start the build process.

With Vale, you can scan the markdown file and check for content that goes against any defined rule you have created. In this example, Vale would return the following error.

 example.md
 1:1  error  Using 'Simply' may come across as condescending.  spectrocloud.condescending
             
✖ 1 errors, 0 warnings and 0 suggestions in 1 file.

That’s the value proposition of Vale, to help you write better by catching things you may have missed or accidentally done that go against your organization’s writing practices. 

Take a peek at Vale’s extension points. You can use these extension points to create all types of rules. The example provided had only one rule in effect, but imagine a scenario where multiple rules are defined, and multiple files are scanned. There are several third-party integrations and publicly accessible writing style guides you can use, such as Microsoft, Red Hat, Google, and others. In the beginning, you can start with one of these and adjust as needed. As you and your team gain more experience and exposure to the tool, you can start diving into authoring your own rules. 

How we Use Vale

Our Docs and Education team uses Vale as part of the authoring workflow. Every pull request that modifies the text in our documentation site goes through a GitHub action that triggers Vale to check modified or newly created markdown files. This check has caught its share of typos, passive language, and other occurrences that go against our style guide. 

We have found that Vale helps supplement the review process, and as writers, we can speed up the review process by focusing more on content and information architecture. Vale does not replace the need for an editorial review, but it does catch mistakes and helps the reviewer validate the text.

Below is an example of a simple typo flagged by Vale during a pull request.

Other teams in our organization are also using Vale to help improve the writing quality of public-facing content that does not undergo a review from the Docs & Education team. A good example of this is the README for an integration we support. We call integrations “Packs,” and we support over 200 of them. Each one has a README, and to help improve the writing quality, our internal development team that supports pack integrations uses Vale to prevent common writing issues. 

Another neat example. The engineering team responsible for maintaining our internal platform API utilizes Vale to prevent the use of unwanted terms in API endpoint names, descriptions, query parameters, and more. Unwanted terms can range from word phrases marked as culture-insensitive, to simple branding enforcement decisions on what a component should be labeled externally.   

Scaling Knowledge

Vale can provide a lot of value to your team and organization out of the box. However, in our opinion, Vale provides the most value in its ability to allow users to create their own custom rules that can be used to enforce a writing style guide programmatically. 

A collection of custom rules can be grouped to form a Style. At Spectro Cloud, we have two different Styles, one is for our internal Docs & Education team, and the other is for any team in the organization that wants to add Vale to their repository and adhere to our writing style. Both Styles are based on our internal writing style guide.

The Style for the Docs and Education team is much stricter and contains unique rules that are only applicable to the documentation repository. This separation allows the Docs and Education to create custom rules for their team, experiment with new rules, and test them for a while before deciding to roll them over to the style that is used by the rest of the organization. 

To make these custom rules based on our writing style guide accessible to other teams, we host them in a GitHub repository as Vale packages. To keep this blog shorter, we won’t cover in detail what a Vale package is, but know that it’s what you use to expose custom rules, Styles, approved and disapproved terms, and other Vale configurations for others to use. In other words, it allows Vale customization to be reusable.  

The diagram below displays the composition of a package at a high level. 

If you want to learn how we expose our Vale packages, check out our public Spectro Cloud Vale packages repository. Take a peek around the code base, and the GitHub Actions. You are also welcome to adopt the ruleset in your organization, or borrow from it as needed. 

Consuming Our Vale Packages

Our internal teams can consume our Vale packages by adding a file named .vale.ini , and a GitHub Actions workflow YAML file to their repository.

‍

The .vale.ini contains the following code snippet instructing the Vale CLI where to find our packages and how to use them.

StylesPath = vale/styles

MinAlertLevel = suggestion

Packages = https://github.com/spectrocloud/spectro-vale-pkg/releases/latest/download/spectrocloud.zip
Vocab = spectrocloud-vocab

[*.md]
BasedOnStyles =  Vale, spectrocloud

The GitHub actions workflow file needs the following content.

name: Vale

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

concurrency:
  group: vale-${{ github.ref }}
  cancel-in-progress: true

jobs:
  run-ci:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    if: ${{ !github.event.pull_request.draft && github.actor != 'dependabot[bot]' && github.actor != 'dependabot-preview[bot]' }}
    steps:
      - run: exit 0

  vale:
    needs: [run-ci]
    uses: spectrocloud/spectro-vale-pkg/.github/workflows/vale.yml@main

Adding the GitHub workflow file to a GitHub repository will automatically trigger Vale to check any modified files during a pull request. If a pull request is in draft mode, it will not trigger the checks. This prevents authors from triggering Vale checks and receiving comments in their pull requests while still working. 

We have authored a set of test cases for every rule in our Vale packages to ensure they work as expected. We verify that each rule behaves as expected by providing a pass and failure scenario test case. 

The two steps above, creating the two files in a repository and copying the code snippets, allow our internal teams to get started with Vale in minutes. It also allows us to scale the knowledge and skills of our Documentation team by helping other teams adhere to our style guide when writing content. We don’t expect non-documentation team members to know the style guide intimately. So, instead, we come to them and provide feedback through the various Vale rules we house in our Vale package.  

Supporting Vale

At Spectro Cloud we take seriously our commitment to the open source community — it's why we build our product on projects like Cluster API, KubeVirt, vCluster and others, and it's why we sponsor projects like Kairos, LocalAI and Validator. 

But we're also proud to put our money where our mouth is and offer financial support for the projects that we love. That's why we want Vale to continue to grow and provide value to other teams and organizations, just as it has provided a lot of value to us. We’re proud to be part of the cohort of organizations that have sponsored Vale and want to ensure its success continues.

Thanks to Vale, we continue to produce top-quality documentation while minimizing common mistakes related to writing that may slip past an editorial review. Ensuring our product documentation is of top quality goes a long way in improving the customer experience. 

If you and your organization want to improve the writing quality and writing practices in your organization, consider adding Vale to your teams’ workflows. We encourage you to take a peek at our Spectro Cloud Vale packages repository and to visit the official Vale.sh documentation to learn more about this fantastic tool. 

And if you want to see the end result of Vale in action, take a tour of our docs site and let us know what you think.