This article has been contributed by Dmitri Popov, Technical Writer at the SUSE Documentation Team. 

Let’s start by stating the obvious. Well-written texts have three basic properties:

• correct spelling and punctuation
• correct grammar
• consistency

Correctness is required

While a spell checker can take care of the first item in the list, you can catch most common grammatical issues using LanguageTool.

The consistency part is tricky, though. Status bar or statusbar? EXT3 or Ext3? Web or web? man page or manpage?

Consistency is key

Sometimes there is only one correct option. Sometimes, both spellings are correct, so you need to make a conscious choice to choose one. Consistency is the raison d’être of a style guide, a codified compendium of rules and practices that must be followed to keep language usage, well, consistent. For writers–and technical writers in particular–having a style guide is a must. But consulting it every time you are in doubt can quickly become a nuisance. And if you are interested in contributing to documentation, without being a technical writer, chances are that reading through the style guide is the last thing you’d want to do.

Vale adds value

This is where Vale comes into the picture. Vale is a grammar, style, and language usage linter for the English language. In programming, linter is a tool that analyzes source code to detect and flag errors, bugs, stylistic errors, etc. in real-time. That’s what Vale does too, but instead of code it works with the English language. Simply put, Vale analyzes the text against the supplied set of style rules, detects problems, and suggests solutions while you are writing.

A style guide is the premise

For Vale to do its job, you need to provide it with a style guide. There are several Vale-compatible style guides you can choose from, including the Microsoft Writing Style Guide, the Google Developer Documentation Style Guide, and others. But since you’re reading this, it’s highly likely that you are interested in SUSE or you work with SUSE products and solutions, so SUSE Documentation Style Guide  is the reference that you’d want to use with Vale. But how? I’m glad you asked.

The project awaits you

During Hack Week 21, I’ve created a Vale-compatible version of the SUSE Documentation Style Guide. All you have to do is to install Vale, add the guide to it, and plug Vale into your preferred editor. The README file provides instructions on how to accomplish that. If you want to contribute, you’ve found an error, or you have a suggestion for improvement, open an issue in the Issues section. I hope you find the project useful!