Write Better, Stronger, More Powerful Technical Documentation with Write-Good! by Matthew Setter

Write Better, Stronger, More Powerful Technical Documentation with Write-Good!

October 12th, 2018

Are the words in your technical documentation strong, sharp, direct, and powerful? Alternatively, are they passive, weasely, replete with clichés and adverbs? If they're the latter and you want to make them the former, then come learn about a tool that uncovers the weaknesses, and helps you improve.

Welcome to the third part of this series, covering five tools that can help you improve the quality of your technical writing skills, and technical documentation. Here, in part three, we’re looking at write-good.

Before we begin

I'm making a sweeping (though not entirely unfair) assumption, this time, that your technical documentation is in English. If it's not, then this tool's not going to be of much use.

However, given that the language of software development is English (along with the language that most readers of this blog), then I think it's a safe assumption to make.

I'll speak for most people I know, when I say that most of us, at least at the beginning, don't start out writing the strongest, sharpest, nor most succinct documentation.

We often qualify statements unnecessarily, weakening their impact. We add copious unnecessary words, making the reader work harder to read what we've written and to understand it. We don't get to the point as quickly as we should. We don't, as Stephen King advocates, "kill our darlings".

I know I'm guilty of these things. All of these things, unless used judiciously, reduce the quality of the technical documentation that we produce.

But knowing what good writing is, and being able to distinguish it from poor writing takes time, training, and practice. It's something that very few of us can learn on our own.

So You Need to Have Tools

You need tools that you use regularly, that can highlight these weaknesses for you, allowing you to decide whether to keep them or not. Write good is just such a tool, one that I've been using that can do just this.

It applies a series of checks to strings and text files, linting them for words that weaken their effectiveness. Here’s the list:

Check Description
passive Checks for passive voice.
illusion Checks for lexical illusions – cases where a word is repeated.
so Checks for so at the beginning of the sentence.
thereIs Checks for there is or there are at the beginning of the sentence.
weasel Checks for "weasel words."
adverb Checks for adverbs that can weaken meaning: really, very, extremely, etc.
tooWordy Checks for wordy phrases and unnecessary words.
cliches Checks for common cliches.
eprime Checks for "to-be" verbs. Disabled by default

How To Install Write Good

Available via NPM, you can install write-good relatively trivially. Assuming you have a relatively recent version of NPM installed, you only need to run the following command:

npm install write-good

How to Use Write-Good

With it installed, you can use it lint English prose, whether in a text string, a single file, or across a range of files. As with broken-link-checker, which we saw in the last part in this series, write-good uses a glob to identify the files to lint, scans them, and prints its suggestions to STDOUT.

So, in the following example, I'm going to lint all AsciiDoc files in modules/developer_manual/pages/general/.

write-good modules/developer_manual/pages/general/*.adoc | less

Below is an example of the output from linting the files. You can see that, while not the clearest to read, it does three things:

  1. Prints out the lines where problems are found.
  2. Underlines the word in the line that is problematic.
  3. Prints out why the word is deemed problematic.
In modules/developer_manual/pages/general/backporting.adoc
We mostly consider bug fixes for back porting. Occasionally, important
"mostly" is a weasel word and can weaken meaning on line 12 at column 3
 fixes for back porting. Occasionally, important
"Occasionally" can weaken meaning on line 12 at column 47
changes to the API can be backported to make it easier for developers to
"be backported" may be passive voice on line 13 at column 23
1.  Make sure the PR is merged to master
"is merged" may be passive voice on line 17 at column 21
ainer if the code should be backported and add
"be backported" may be passive voice on line 18 at column 50

How To Get More Readable Output

While it's not that clear, a new line that starts with ------------- separates each match. If you want output that is easier to read, you need to use the --parse option. When in effect, the previous output looks like the example below.

write-good --parse modules/developer_manual/pages/general/*.adoc

# File paths shortened for readability
modules/**/backporting.adoc:12:3:"mostly" is a weasel word and can weaken meaning
modules/**/backporting.adoc:12:47:"Occasionally" can weaken meaning
modules/**/backporting.adoc:13:23:"be backported" may be passive voice

You can see that it prints:

  • The file, line, and starting character of the problematic word
  • The problematic word; and
  • The description of the error

I don't know about you, but the --parse switch makes the output much easier to read, and much easier to pipe to other tools, such as grep, sed, and awk.

How To Enable Only Select Checks

By default, all the checks are run. However, if you're beginning your journey toward strong prose, or you're only beginning on an old documentation base, one that saw better days, it's best to start off gently.

To do that, you can take one of two approaches. You can either:

  1. Only activate one rule
  2. Deactivate all rules that you don't want

In the first example, we're going to activate just one, specific rule. I'm a big user of 'so', so that's what I'm going to only check for it. I'll do that by adding the --so option to the previous command, as in the following example:

write-good --parse --so modules/**/*.adoc

# File path shortened for readability
modules/**/webgui/tagging.adoc:55:0:"So" adds no meaning

It turns out I didn't use it as much as I thought I did in the ownCloud documentation. I had to drastically alter the glob to find the single file where "so" was used. As before, you can see the file, line, character, occurrence of "so", and why it's considered unhelpful.

Now, let's take option two, and individually, deactivate several checks. Specifically, we're going to deactivate weasel, adverb, and cliches. Here's what the command will look like:

write-good --parse --no-weasel --no-adverb --no-cliches modules/developer_manual/pages/general/*.adoc

# File path shortened for readability
modules/**/backporting.adoc:13:23:"be backported" may be passive voice
modules/**/backporting.adoc:17:21:"is merged" may be passive voice
modules/**/backporting.adoc:18:50:"be backported" may be passive voice
modules/**/backporting.adoc:31:66:"is announced" may be passive voice
modules/**/backporting.adoc:38:0:"is fixed" may be passive voice

How to Lint a Text String

Now that we've looked at the different ways of checking a series of files let's finish up by looking at how to lint a string. Why? Well, you might not be sure about a particular line of text in a file.

Alternatively, you might have copied a string from the internet that you're not sure about. So, to do that, use the --text option, as in the following example.

write-good --text="Lorem ipsum dolor sit amet, consectetur adipiscing elit."

A word of warning, if only for me. However, if you print out the Usage instructions (-h), you'll see the following:

    --text <text>      provide direct text input instead of glob/file name

From that, you'd rightly think that the command should be the following, not the previous example.

write-good --text "Lorem ipsum dolor sit amet, consectetur adipiscing elit."

However, if you try it that way, you'll see the following output to the console:

"Lorem ipsum dolor sit amet, consectetur adipiscing elit." is not a valid argument.

Please keep that in mind.

In Conclusion

And that's how to use the sublime write-good English prose linter, to lint text strings and an array of files. While it's not perfect and could have more features, it does an excellent job.

What do you think? Are you keen to give it a try? Have you already tried it but use something else?

Please share your experience in the comments.

Matthew Setter. Ethical Hacker, Online Privacy Advocate, and a Software Engineer.

Matthew Setter

Software Engineer, Ethical Hacker, & Online Privacy Advocate.

Matthew Setter is a software engineer, ethical hacker, privacy advocate, & technical writer, who loves travelling. He is based in Nuremberg, Germany. When he's not doing all things tech, he's spending time with his family, and friends.