Linting Technical Docs for AI Readability Using Vale

[Harshit Satyaseel]

When I started learning more seriously about documentation for AI systems, I noticed something I had probably been ignoring for a long. A lot of documentation problems are not really writing problems but are consistency problems.

The API is PlatformClient on one page and platformClient in an example on another. If you write technical documentation, you can relate to this.

In my docs, one feature is called Form Filling in the navigation, form filling in the body, and Form-Filling somewhere else.

Someone writes:

You might need to create a session before calling the API.

But the session is actually required. None of these things would make me reject a documentation page.

You might even read the page, understand what it means, and move on. But when you maintain a large documentation set, these small differences start showing up everywhere, and now that the same documentation is also being used by AI assistants and RAG systems, I started paying more attention to them.

Not because I think documentation should be written for AI. It should or shouldn’t, but if we can make the documentation clearer and more consistent for people, we also give machines cleaner information to work with.

That is where Vale comes in.

The style guide problem​

Technical writers love style guides and my docs also has one. We create them for everything like

• Capitalization
• Product names
• API terminology
• Headings
• Voice
• Sentence length etc.

And eventually it becomes a large document hard to maintain, and something a person has to remember.

You can tell a writer:

Always use PlatformClient

Six months later, someone writes Platform Client

You can tell everyone:

Don't use vague language in instructions.

Another writes "you might need to..." This is normal when you have multiple writers, hundreds of pages, and documentation that keeps changing. So instead of putting another rule in a document and hoping everyone remembers it, I started thinking about which rules could simply be checked automatically.

That that is where I used Vale. Vale is a prose linter. It can run against Markdown and MDX and lets you define your own writing rules. It is basically the same idea as linting code it just that you are linting documentation here.

How do start using vale​

Don’t start by creating 100 Vale rules. This is what most beginners do. Instead, first rule is to protect information. Let’s understand this. Product names, API identifiers, Important terminology, these are the things that should be written in a specific way.

For example, imagine that the official feature name is:

Form Filling

I don't want this appearing randomly across the documentation:

Form filling
form filling
Form-Filling

Sometimes lowercase form filling might be correct in body text which is fine but a good Vale rule should understand the context not the rule it self.

For example, I might want Form Filling in a title but allow form filling in normal prose.

Vale lets me create rules for those cases instead of relying entirely on manual review.

A simple rule could look like this:

extends: existence

message: "Use 'Form Filling' in titles."
level: error

nonword: '\bForm filling\b'

scope: title

It is a very small rule. But that is the point. I don't need Vale to understand my entire documentation strategy, it just need to catch the things I already know are wrong.

Vale language​

There is another category that I find interesting in vale

Words like:

maybe
might
could
often
seems

These words are not automatically bad. Sometimes "might" is exactly the right word.

But technical documentation has plenty of places where we use these words because we haven't been precise enough.

For example:

You might need to create a session before sending audio.

If the session is required, why say "might"?

Just say:

Create a session before sending audio.

So I can use Vale to flag words like might or could:

extends: existence

message: "Avoid vague language. Be specific."
level: warning

nonword: '\b(maybe|might|could|often|seems)\b'

scope: text

Notice that I used warning. I don't want the build to fail every time someone writes "could”, instead I want the writer to stop for a second and decide whether the sentence can be made more precise and this distinction matters a lot.

Vale for API identifiers​

I am much stricter with API identifiers. If the actual SDK class is:

PlatformClient

then I want the documentation to say exactly that.

Not:

platformClient
Platform Client
platform client

The same goes for parameters:

emr_encounter_id
session_id

These aren't style preferences but are identifiers. If I get the capitalization of a normal sentence wrong, nobody's application breaks but If I get an API identifier wrong in a copy-paste example, there is a much bigger problem.

This is also where AI-generated code makes consistency more important. If an AI system gets PlatformClient from one page and platformClient from another, I would much rather have caught that inconsistency in the source documentation than try to fix the generated answer later.

Sentence length is another thing Vale can check. I like shorter sentences in technical documentation not because every sentence needs to be short, but because long sentences often contain several instructions that should have been separated.

For example:

Before calling the endpoint, make sure the session exists, that it is active, and that the session ID returned when you created it is the same ID you use in the request.

There are several pieces of information here.

I would probably write:

Create a session before calling the endpoint.

The session must be active.

Use the session_id returned when you create the session.

Much easier to scan, maintain, and reuse as individual pieces of information. I would still make sentence length a warning. I don't want a linter forcing writers to write unnatural prose just to make a number happy.

Where Vale actually fits​

For me, Vale makes the most sense when it becomes part of the normal documentation workflow. As a tech writer I can get feedback in the editor itself. The same checks can run before committing and then CI can run them again when the documentation goes through a pull request.

A simple GitHub Actions job looks like this:

name: Vale

on: [pull_request]

jobs:
  vale:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: errata-ai/vale-action@v1
        with:
          files: '**/*.mdx'

When you work with vale, be careful about what blocks a PR. An incorrect API identifier might be an error or vague word should probably be a warning. A style suggestion might just be a suggestion. If everything becomes an error, you will eventually start treating Vale as noise and this gets frustrating over time.

Where Vale fits in AI workflow​

I don't think Vale makes documentation "AI readable" in some special technical sense. What it does is help remove some of the mess from documentation like consistent terminology, correct identifiers etc.

My workflow has changed a bit with Vale. Now I also think about how another system might consume the same page. Developers might understand that Form Filling and form filling refer to the same thing. A documentation search system may still have to deal with the difference. But an AI assistant may retrieve several pieces of documentation and use them as context. Using vale make your source material less ambiguity to deal with. That is the real reason why linting is important in the AI world.

Conclusion​

I have always thought of documentation quality as something that comes from many small decisions. Like:

• Writing right sidebar for and API.
• The right example.
• A clear heading that is easy to search and make sense as per that page topics etc.

Vale doesn't replace any of that work. It just lets you automate some of the decisions we keep making manually over the time, and as your documentation grow and gets consumed by AI systems, I think that is worth doing.