Linting for technical writing

This package contains rules based on the GOV.UK Technical Style guide and is designed to work with the linting tool Vale. You can find more information about Vale on its website.

Errors raised by the linter will show for each file:

• the line and character number of the issue
• the severity level of the issue (error, warning, suggestion)
• a description of the issue
• the path to the rule that flagged the issue

If you would like to suggest a new or updated rule please open a new issue on this repository.

Installing the linter on your local machine

1. Install Homebrew.
2. Install Vale.

Adding the tech-docs-linter as a package to your config file

To use the linter (Vale), you must provide a config file which describes where the rules for the linter are located. Confirm that a .vale.ini exists at the root of your repo and that the url for the tech-docs-linter zip file is provided through the Packages field. Here is a template config file for reference.

Rules

The table below is a summary of the rules defined in /styles/tech-writing-style-guide/.

Name	Summary	Severity level
acronyms	Acronyms should be defined the first time they are used.	Error
common-misspellings	Highlight words or service names that are commonly misspelt.	Error
brackets-in-headings	Check page headings for brackets.	Error
consecutive-headings	Hilights sections that could be broken up using sub-headings.	Suggestion
H4	Hilight H4 headings for page structure review.	Suggestion
H5 and H6	Check for headings greater than H4 as these should not be used.	Error
headings-length	Highlight headings with over 65 words.	Warning
headings-with-no-content	Check for headings that have no content between them (includes tables and diagrams without lead in lines).	Warning
skipped-heading-levels	Checks order of nested page headings for accessiblity.	Warning
sentence-length	Highlight sentences with over 25 words.	Warning
words-to-avoid	Check for any words or phrases on the words to avoid section of the style guides.	Error
terminal-punctuation	Check headings do not finish with sentence ending punction such as full stops or question marks.	Warning
words-to-avoid-unless	Check for any words or phrases on the words to avoid section of the style guides which have an 'unless' caveat.	Warning

Running the linter on your local machine

By default, Vale must be run from the same directory as this config file, unless the --config flag is provided with a path.

1. In a terminal window, navigate to your repo
2. Run vale sync to download the latest tech-docs-linter package and unzip this to your StylesPath listed in your config file
3. Run the command vale . to lint the entire repo or provide a path to a directory to lint only that directory for example: vale source/new-starter-guide/*.erb

You can format the output to suit your needs, for example running the linter in your CI/CD pipeline to make a judgment on where to release or review your content. This project contains an example Rakefile that you can use. The example will format the output into a human-readable table and summary, for example:

File	Line	Severity	Message	Rule
build/acronyms/3-common-4-not-half-defined.html	118	ERROR	'KJE' must be defined in the first instance	tech-writing-style-guide.acronyms
build/acronyms/3-common-4-not-half-defined.html	124	ERROR	'LLPWA' must be defined in the first instance	tech-writing-style-guide.acronyms
build/common-misspellings/single-misspelling.html	109	ERROR	The GOV.UK style guide recommends using 'One Login' instead of 'OneLogin'	tech-writing-style-guide.common-misspellings

======================================== 📊 Vale summary

Errors: 36 Warnings: 18 Suggestions: 0

Testing linting rules

The linter contains a cucumber test suite, found in the /features directory. Tests are written in using scenario based Behavior Driven Development (BDD). This approach means non-technical maintainers can understand and update the behavior of the linter, with support from technical colleagues to implement step_definitions. If you are new to cucumber this repo contains an example feature.

You can install cucumber using bundle install or gem install cucumber. For more details see the documentation.

To run the full cucumber suite you can run the following command:

bundle exec cucumber

To run a single file add the filepath to the feature, for example:

bundle exec cucumber features/style_guide/misspellings.feature

To run a single scenario in a feature file, add the line number. For example:

bundle exec cucumber features/rules/style_guide/acronyms.feature:29

Releasing an update to the linter

Before releasing a new package you should:

• make sure the CHANGELOG has been updated
• add a new feature file to the cucumber test suite and define the rule
• ensure all the tests pass

To release an update:

• change directory to the styles folder
• create a zip package of the tech-writing-style-guide folder: zip -r tech-writing-style-guide.zip tech-writing-style-guide
• select Draft a new release from the releases page for the linter
• upversion the tag and add information about the changes that have been made
• upload the tech-writing-style-guide package

Additional Resources

Template Vale config

StylesPath = vale-styles 
Packages = https://github.com/alphagov/tech-docs-linter/releases/latest/download/tech-writing-style-guide.zip

# Local Config
[formats]
erb=md
MinAlertLevel = error
[*.{md,org,txt,erb,html}]
TokenIgnores = (\*{2}(.+)\*{2})

BasedOnStyles = tech-writing-style-guide