Build tools that can be used to analyze technical documentation and generate feedback or suggestions on how to improve it. Use a general-purpose prose linter as the basis for the tools.

Context

In a complex ecosystem of tools, codebases, and APIs used by a global community of contributors, technical documentation is a critical resource. But writing high quality docs can be difficult. To make it easier to write good documentation, we will build prototypes of tools that can provide feedback about documentation either as it's being written, during publishing, or after it's live.

To that end, we will use an existing, general-purpose prose linter with a custom configuration based on our style guides. We will create proof-of-concept solutions embedding the linter in our processes, for example in GitLab CI pipelines.

We hope that with tools built in this project we'll be able to empower new writers, increase current writers' confidence in their docs, and improve documentation quality.

Why linting?

Linting is the process of analyzing code in search of errors, bugs, and suspicious constructs (source). It's a crucial and familiar part of many development processes. It allows developers to automate static checks against a set of rules, for example defined in a style guide.

Technical documentation isn't code, but it's also governed by a set of clear rules. Technical writers and editors often codify them in style guides of their own, but these are often a lengthy read because natural language can get complex. An automated linter that checks your documentation during writing or reviewing can make an existing style guide much more accessible and easy to use.

Outcomes

In the course of this project, we've created artifacts described in the following sections.

Note:

• All tools designed in this project were developed by the Technical Documentation Team and function as prototypes. In the event of broad adoption of these tools, they might need to be improved, refactored, or rewritten.
• The focus in this project is on linting documentation written in English. Tools and configurations developed here don't work with other languages and aren't translatable. However, we hope that some configurations, designs, and lessons learned in this project will be directly transferable to similar projects for other languages.

Linter configuration

Linter configuration with a programmatically codified version of selected style guide rules

Vale expects its configuration in the .vale.ini file to be located either in user's home directory, or in the project home directory. This configuration file should also specify the location of the styles directory, which contains the style rules.

The linter-quickstart repository provides the .vale.ini file, and the .styles directory. The .styles/Wikimedia directory contains YAML files with style guide rules codified using Vale's rule syntax. Each file defines a rule or rules and a severity level.

Placing the .vale.ini file and the styles folder in the home directory on your device should be enough to run Vale in CLI mode and as a language server.

GitLab CI configuration

GitLab CI configuration with the linter available for importing in custom pipelines

The linter-quickstart repository contains a GitLab CI configuration file with a linting job that can be copied to your .gitlab-ci.yml file in a different repository. This linting job requires two environment variables to be defined for the purpose of specifying a Vale configuration and a documentation directory. A job returns linting information in the form of direct output from Vale running on the specified files or directories.

The pipeline job fails when linted files contain any style errors, and succeeds if the linter outputs only warnings or suggestions. There are currently no rules with an "error" severity level in the .styles directory.

Web-based tool

Web-based tool for linting wiki page content

The documentation linter web app is a Toolforge tool with a simple interface. It allows users to request linter output for a single page on mediawiki.org or Wikitech. Linter output isn't cached - the linter runs on every request.

The app displays a separate section for each detected issue. Each section contains information about the type of feedback, rule, a line or section that feedback applies to, and any other information necessary to improve the documentation. The application stores no history or context, merely runs the linter on current page content. As page content changes, the app will display fewer issues when the docs improve, and more issues if the changes introduce new problems.

The web app is written in Python using Flask. It serves as a thin wrapper around Vale and offers little functionality on its own. It doesn't require authentication and has a simple architecture, with back-end providing most of the functionality. The app is designed to minimize CPU, RAM, and bandwidth requirements for its users.

The app repository includes linter configuration and the full set of style rules.

Documentation

• Documentation landing page
• Documentation for the linter and GitLab CI configuration
• Documentation for the web app
• Linter rule reference

Plan

Note: Tasks can run in parallel.

Phase 1

• Pick a linter T388111: Choose a linter to use in the linting tools project
• Evaluate rules and guidelines from the available style guides
• Select the rules to codify programmatically
• Codify the selected rules in the language of the linter
• Specify any other configuration options necessary for the linter to run
• Test the linter and the configuration on existing documentation
• Write instructions on how to use the linter and the configuration in a local development environment

Phase 2

• Design a GitLab CI pipeline documentation linting step
• Create a CI configuration that can be included in a pipeline
• Test the configuration in a real project
• Consider the steps necessary to replicate the functionality for projects in Gerrit
• Write instructions on how to use the linter in any project pipeline

Phase 3

• Design a web-based tool for linting wiki page content
• Develop the tool
• Deploy the tool
• Test the tool on existing wiki docs
• Document the tool