The Vale Workflow

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

A screenshot of the Vale Server v1.3 dashboard
  • 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.

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.

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.

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.

Putting it all together: The CI service

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

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

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:

  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.
See Configuration and Styles for more information.

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.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Joseph Kato

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