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.
• Locally: Local usage typically involves using one of Vale’s editor plugins to provide on-the-fly linting of your content.

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.
• Check: Vale’s functionality is exposed through extensible “checks” that perform abstract tasks such as checking the length of certain text segments (e.g., sentences and paragraphs) or searching for a particular token in a text document.
• Rule: A “rule” is a check that has been given a concrete task — for example, ensuring that sentences contain no more than 25 words.
• Style: A “style” consists of multiple rules that come together to enforce the guidelines of a certain organization, guide, or application. Within a given style, rules are assigned an ID of the form <style name>.<rule name>.
• StylesPath: A directory containing all Vale-related files.
• .vale.ini: An INI-formatted configuration file that serves as the primary means of controlling the behavior of Vale.
• Vale Server: A commercial desktop application built on top of Vale that brings a refined experience for individual writers, including a fully managed StylesPath and the ability to use local Vale configurations on the web.

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.
• Updating your StylesPath is time-consuming. The current find-download-unzip-copy process is far from ideal, especially when managing multiple projects.
• You can’t use your local Vale configurations on the web. While Vale has existing plugins for text editors, it doesn’t support web-based applications such as Google Docs and web browsers.
• You can’t customize or override CI-focused configuration files locally. As mentioned in the previous section, it’s common to want only error-level rules enabled for CI environments. This means that’s all you have access to when working on content locally as well.

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.
• Vale Server includes many features that make managing multiple projects and configurations locally easier but isn’t meant for CI environments.
• Both Vale and Vale Server are designed to allow a high degree of workflow customization: all configuration files are (machine-readable) plain text files that can be incorporated into automation scripts.

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