liveBook · Manning

Prose linting

As explained in Automating API Delivery

Prose linting is automated analysis of written documentation for punctuation, spelling, grammar, and language-style problems.

Prose linting automatically scans API documentation for punctuation, spelling, grammar, and language-style problems. Unlike basic grammar checkers, prose linters support custom rules for organizational style, tone, branding, jargon, redundancy, clichés, and vocabulary. section 8.10

Deploy prose linting as an automated documentation-quality control:

  • Store API guide documentation as Markdown in version control so pipeline jobs can inspect changes. section 8.10
  • Add prose linting to pull-request merge criteria alongside API linting, breaking-change checks, and work-ticket validation. section 8.2
  • Configure Vale with a project .vale.ini file, selected style packages, and file-specific rules. section 8.5.5
  • Run the configured linter against the API documentation directory and inspect its workflow output before merging. section 8.5.5

Vale in a GitHub Actions review job

A project can configure Vale to use the Microsoft Writing Style Guide and apply Vale and Microsoft styles to Markdown files. A workflow step downloads Vale 2.15.4, installs it on the runner, synchronizes configured packages with `vale sync`, and lints `apis/docs` with the project configuration. Vale can also run through a dedicated GitHub Action. section 8.5.5

StylesPath = ./../.github/styles       #1
MinAlertLevel = suggestion                 #2

Packages = Microsoft      #3

[*.md]                             #4
BasedOnStyles = Vale, Microsoft     #5

Inspect the compact .vale.ini example to see the styles path, alert threshold, Microsoft package, Markdown selector, and inherited styles. section 8.5.5

      - name: Prose Linting
        run: | 
          wget -nv 
 https://github.com/errata-ai/vale/releases/download/v2.15.4/
 vale_2.15.4_Linux_64-bit.tar.gz
          mkdir bin && tar -xvzf vale_2.15.4_Linux_64-bit.tar.gz -C bin
          export PATH=./bin:"$PATH"
          cd pr-branch/chapter8
          vale sync --config=
 'pr-branch/chapter8/.vale.ini'       #1
          vale pr-branch/chapter8/apis/docs 
 --config='pr-branch/chapter8/.vale.ini'      #2

Inspect the workflow listing for the concrete installation, package synchronization, and documentation-linting commands. section 8.5.5

How Automating API Delivery covers it

How deep it goes
Explains tool choices, configuration, installation, execution, and pipeline placement, but defers detailed style-rule authoring.
Examples
Uses Vale, textlint, and proselint, with a Vale configuration and GitHub Actions commands targeting Markdown API guides.
What it assumes
Assumes version-controlled API documentation and a pull-request workflow, while introducing prose-linter configuration and execution.
What you can do after
Apply it via Vale in a pull-request workflow to detect editorial problems before API documentation merges.
How it connects
Connects prose linting with API linting, breaking-change checks, version control, pull requests, CI/CD, and style guides.
Cover of Automating API Delivery
liveBookmanning.com
Read Automating API Delivery on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Automating API Delivery. The section links point to the parts of the book it draws on.