Write with a little help from a stylish friend

Share
Share

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 statusbarEXT3 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!

Share
(Visited 24 times, 1 visits today)
Avatar photo
2,631 views
Meike Chabowski Meike Chabowski works as Documentation Strategist at SUSE. Before joining the SUSE Documentation team, she was Product Marketing Manager for Enterprise Linux Servers at SUSE, with a focus on Linux for Mainframes, Linux in Retail, and High Performance Computing. Prior to joining SUSE more than 20 years ago, Meike held marketing positions with several IT companies like defacto and Siemens, and was working as Assistant Professor for Mass Media. Meike holds a Master of Arts in Science of Mass Media and Theatre, as well as a Master of Arts in Education from University of Erlangen-Nuremberg/ Germany, and in Italian Literature and Language from University of Parma/Italy.