Vale CLI vs AI

How to combine Value CLI + AI for Technical Writing that gains claps from stakeholders?

If you are a technical writer that struggles with style guide inconsistencies, I have found a solution for you. Believe me, if you tell me to read a style guide that spans over 100 pages, I wouldn’t read that — thanks to these short videos on social media that has made brain rot.

Enters Vale CLI combined with LLM

I used to post often about how Vale CLI can fix style guide issues, I later realized that the tone, audience, and style varies for documentation and Vale CLI cannot do that. On the other hand, AI cannot fix style guide inconsistencies as expected.

In this post, we will cover:

• What is Vale CLI?
• How to use it with LLM(It’s just copy paste, no big deal. I am not doing any rocket science here.)
• Tool, Prompt templates to get started.
• Usecases

What is Vale CLI?

Vale CLI is a command line interface tool designed to lint(a process to check your code or text for errors, style inconsistencies—commonly used by developers) your content and do style checking.

Vale CLI is not your grammarly, it follows guidelines that is defined either by you or imported from somewhere, for example MSTP, Google. It checks your content if it follows the guidelines, and provides you with suggestions, validations, errors.

Features of Vale CLI

• Customizable Style Guides: Define your own style guide, edit the existing ones to tailor it your requirement.
• Multi format: Supports various formats such as Markdown, AsciiDoc, Latex.
• Disabling Vale: Able to disable vale for ignoring contents.
• Real-time feedback: Ease of integration with IDE like VS Code, or as part of CI/CD pipelines.

Installing Vale CLI

Install Vale CLI on your system to begin linting your documentation files for style, clarity, and grammar. This helps technical writers to follow a writing style across all their documents.

The following steps are to be followed in Windows Machine. I will be demonstrating it with Markdown contents.

Pre Requisites

• IDE like VS Code, Atom
• Knowledge on using IDE
• Existing Project with Markdown files
• Admin Privilege for installation

To install Vale CLI,

1. Open your project folder in VS Code, Go to Terminal, and run the following command.

    choco install vale
   

2. Verify the installation with the following command.

    vale --version
   

   Vale CLI is installed and ready to be configured for style and grammar checking in your documentation project

Configuring Vale CLI

Configuration of Vale CLI is done through creating .vale.ini file and connecting it to predefined or custom style rules.

Prerequisites

• Install Vale CLI on your system.
• Familiarity with YAML format(no big deal, you can use LLM to get the configuration for Vale CLI)

To Configure Vale CLI

1. Create a .vale.ini file in your project root directory. This file tells Vale CLI which style rules to apply.

2. Add the following configuration, I am using Microsoft Style Guide.

    StylesPath = styles
    MinAlertLevel = suggestion
    Packages = Microsoft
    [*.md]
    BasedOnStyles = Microsoft
   

3. Save the file and enter the following command to sync the packages.

    vale sync
   

   The packages are downloaded and synched. You will see a styles folder created with multiple .yaml files that contains all the style guide rules.

4. To run vale on a file, run the following command.

    vale <your file name>
   

   The output is showing errors(I used my initial draft and wanted to see the errors that I will encounter, and yes, I have lots of them.)

   

How to combine with LLMs?

After running Vale CLI on your docs, use a LLM to revise flagged content for clarity, consistency and tone.

Prerequisites

• Vale CLI installed and configured with style guides
• A flagged Markdown file
• Access to LLM(ChatGPT, Ollama, Claude or anyone of your choice)

To run with LLM,

1. Copy the flagged sentence for review.
2. Prompt an LLM to improve the sentence. For example,

    Improve the following sentence for clarity and tone, based on a technical writing style guide (e.g., Microsoft or Google). Avoid passive voice and vague terms:
   
    “Vale CLI is installed on your system”
   
   

   Example LLM output: Revised: “Install Vale CLI on your system.”

3. Apply the revision back to your document. The file is cleared of previous alerts.