The Vale Workflow

An introduction to common Vale (Server) workflows and use cases.

A screenshot of the Vale Server v1.3 dashboard

With Vale rapidly approaching v2.0.0 and the release of the Vale Server desktop app, the amount of possible workflows and use cases is at an all-time high. For the sake of this post, we’ll be focusing on the two basic classes of use cases:

  • Remotely: Remote usage typically involves running Vale on a virtual machine through a Continuous Integration (CI) service.

The goal is to cover the basic details of each workflow type and provide some general best practices. However, there’s no “correct” way to use Vale and you’ll likely end up mixing and matching aspects from each to suit your individual needs.

Terminology

Before we get into discussing how Vale can be used, we’ll cover some of the terms that you’ll encounter in this post and other documentation.

  • Vale: An open-source, command-line tool that brings code-like linting to prose.

The remote environment

The remote environment has a number of challenges but, in general, this is where Vale (the command-line tool) tends to excel.

Typically, Vale is used remotely in situations where multiple writers are contributing to the same repository. The goal here is to act as sort of a “last line of defense” (with individual local configurations being the first; more on those in the next section) that ensures published content is typo-free and on-brand.

The third-party base style [optional]

The first step in creating a remote test suite with Vale is to decide if your organization wants to follow a third-party style guide such as the Microsoft Writing Style Guide or the Google Developer Documentation Style Guide.

In general, these styles should be treated as read-only and not be checked into version control. Instead, you should fetch the latest release using a script similar to the example below:

Installs the latest release of a remotely hosted style (in this case Microsoft) into /styles.

The organization-specific style

The organization-specific style should be named after your organization, checked into version control, and implement all of your custom guidelines.

In general, it’s best to only enable error-level rules in remote environments. This allows you to keep your CI output readable and fail builds whenever a rule is broken.

Suggestion- and warning-level rules can be enabled as a matter of preference (via Vale Server) by each of your contributors within their tools of choice.

At the very least, an organization-specific style should implement a rule named <your-org>.SpellCheck:

Whenever <your-org>.SpellCheck reports a false positive, you can add the word to StylesPath/vocab.txt—ensuring you never inadvertently publish misspellings.

Additionally, if your custom guidelines or exceptions differ from your base style, you should make all base style adjustments by disabling the base rule and implementing your own variation:

Putting it all together: The CI service

After implementing the suggestions above, you should have a directory structure similar to the following:

NOTE: While we’re using Travis CI as our example CI service, the concepts should translate fairly well to other services.

├── ci
│ ├── scripts
│ │ └── get-styles.sh
│ └── styles
│ ├── MyOrganization
│ │ └── SpellCheck.yml
│ ├── Microsoft (added to .gitignore)
│ │ ...
│ └── vocab.txt
├── docs
│ ...
├── .vale.ini
├── .travis.yml
├── .gitignore

In your .travis.yml file, you’ll want to install Vale and your styles:

If you’d like to see this workflow in practice, check out either Linode’s Guides and Tutorials or Vale Server’s documentation.

The local environment

While remote testing environments are useful for collaborative projects, the most common use case for Vale is simply through one of its available plugins. In other words, it’s used by a single writer looking to improve their content — similar to how they might use software like Grammarly.

The issues with Vale

While Vale can be used in this fashion, there are a number of (potential) sticking points:

  • Managing multiple .vale.ini files can be a pain. If you work on multiple projects (maybe you contribute to a few publications with different guidelines) that don’t have a dedicated .vale.ini, you’re forced to either maintain multiple copies of your global configuration (in $HOME) or update this file whenever you switch projects.

The case for Vale Server

Vale Server was designed to refine many of the rough edges of Vale when it comes to local usage. In order to demonstrate this, we’ll walk through an example of using Vale Server as a single writer working on a few different projects. Consider the following scenario:

We want to have a generic style that includes advice from proselint and write-good. We’ll use this style for our everyday writing in our text editor.

Additionally, we contribute to the Vale Server documentation, which has its own CI-focused .vale.ini file (this could be any project that has a .vale.ini file, though). When working on content related to this project locally, we want to replicate the CI results with suggestion-level alerts, proselint, and write-good enabled.

Here’s how we can implement such a system using Vale Server.

  1. Install proselint and write-good from the dashboard (if you’re using a third-party base style, you’ll want to install it here too):
Click the Open Dashboard… option from the context menu and then Styles from the sidebar.

This will allow you to stay up-to-date with all future updates, bug fixes, and improvements to these styles.

2. Create a project for your generic guidelines, which we’ll call General:

See Configuration and Styles for more information.

Now, you’ll see the CI results with your overrides applied whenever you work on the Vale Server documentation locally. When working on content that doesn’t have an associated Vale configuration file, Vale Server will simply use the General configuration.

See Compatibility Mode for more information about how local overrides work.

Summary

In this post, we discussed the primary use cases for Vale and Vale Server. Some key takeaways from this post are:

  • Vale is ideal for remote CI environments but lacks flexibility when it comes to local editing.

If you have questions or comments, feel free to open an issue at either the Vale or Vale Server repositories.

An open-source software developer with interests in natural language processing, data science, and collaborative writing. More @ https://github.com/jdkato.