Vale notes #3: Things start rolling

Last week, I did separate walk-throughs with two writers. My intention was to gain insight into the issues a typical user might encounter, and to use that information to improve the “getting started” repo I had created. I helped them install, configure, and start using Vale on their systems.

Installing Vale by using brew was problematic, so we installed the precompiled Vale binary instead. We also copied the .vale.ini configuration file and /styles directory to their doc project and updated the configuration to work with .adoc files.

However, when we ran Vale against one of their .adoc content files, we got a mysterious error. Searching online didn’t help us solve the issue right away. I made a mental note to try to reproduce the error later. The writer had been preparing a presentation on Vale for his documentation project team, but given these setbacks they decided to delay that presentation.

The second writer completed the installation process on their own. Our meeting was more of a conversation than a walkthrough. It seemed like they were ready for a style that was more Red Hat-specific than the generic ones I provided.

This weekend, I put my insights from those two walkthroughs to work by completely updating the getting started repo, https://github.com/rolfedh/studious-fortnight:

  • Removing the previous /styles folder and .vale.ini file.
  • Adding the .vale styles folder and .vale.ini that Fabrice and Yana developed for the Che eclipse documentation project.
  • Updating and expanding README.md with new information to help you get started with using Vale.
  • Adding a “Troubleshooting common errors” topic to help newcomers identify and correct common issues.
  • Added a “Vale at Red Hat Blog” blog to the repo.

That blog will cover information similar to project and release notes. In contrast, these “vale notes” posts will focus more on my personal insights.

Vale notes #2: Talk to experts and stakeholders

In addition to eating my own dogfood, I started finding and talking to experts and stakeholders.

For experts, I went to folks inside and outside Red Hat. At Red Hat, I talked to Fabrice Flore-Thebault and Yana Hontyk. Last year, they presented on using Vale with their documentation sets: Eclipse Che and CodeReady Workspaces. I talked to them about their workflow, the issues they had fixed, and results.

Outside Red Hat, I pulled together an unconference session at Write the Docs Portland conference with Mike Jang from GitLab and Jodie Putrino at NGINX. They spoke about their differing approaches to rolling it out at their organizations. Lynette Miles at TAG1 Consulting also contributed.

For stakeholders:

  • I talked with my manager, who was supportive.
  • I arranged a meeting for Yana and Fabrice to present their work to a small group of writers, content strategists, and managers who had expressed an interest in rolling out Vale. The group expressed a lot of interest, and we agreed there should be some follow-up actions, like additional pilot programs.

As an aside, Fabrice and Yana’s presentation included the following impressive graph. It shows how they iterated on both the documentation and Vale style rules to achieve nearly zero errors, both real errors and false positives, over the course of almost two years:

To prepare for the follow-up, I have created a repo that contains a preliminary set of Vale config files and styles: https://github.com/rolfedh/studious-fortnight (definitely a work-in-progress).

Vale notes #1: Eating my dog food

I’ve heard complaints about the peer review process at a variety of organizations where I’ve seen it in use. To simplify, they sound like this:

  • Writers: When I fix a set of issues and resubmit the PR, the reviewer(s) come up with a new set of issues.
  • Reviewers: I keep flagging the same set of stupid !%$%*$# issues.
  • Everyone: Ugh. This takes too much time and effort.

In some cases, the peer review process can be demoralizing and spark interpersonal conflicts.

Looking for a solution to this issue, I turned to Vale, a style linter that has been gained traction at a variety of organizations, such as GitLab, NGINX, and elsewhere. At Red Hat, a couple of doc projects have been using it for over a year and there seems to be growing interest in expanding its use.

My first step was to start using Vale to get hand-on experience using it: eat your own dog food, etc. In my enthusiasm, I popped $57 for a Vale Server license.

Installing Vale Server wasn’t hard. Finding and configuring the pair of plugins to make it work with my Atom editor was a little confusing. Setting up the single plugin for VS Code was easy.

I installed all the built-in styles for Vale Server, but then had trouble applying them to my docs. Installation is not enough. One must also create a project in Vale Server and configure it to use the styles.

Overall, the process was a bit tricky enough that I realized rolling it out to a team of writers would require documented procedures, tutorial videos, and live support.

It’s also unclear whether my organization would commit to purchasing Vale Server licenses at first. So, I would need to figure out how to roll out Vale, the CLI tool, instead of Vale Server. To make the distinction clear, I’ll refer to Vale as Vale CLI from now on.

Vale CLI is simpler to install and configure than Vale Server. However, I believe Vale CLI alone doesn’t integrate with editors like Atom and VS Code. With Vale CLI, you get all your feedback by running the vale command against your file or files from the CLI. For example:

$ vale README.md

The output looks something like this:

Typical feedback from Vale CLI

In some ways, it’s less distracting to get with this command line feedback after you write a block of content. Vale Server highlights issues in your text editor when you save your current text. In other words, with Vale Server, the feedback is both more immediate and in some ways distracting. Six one way, half-dozen the other.