Write Stronger and More Powerful Technical Documentation with Write-Good!

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

Before we begin

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.
• Copious unnecessary words, making the reader work harder to read what we’ve written and to understand it.
• Don’t get to the point as quickly as we should.
• Don’t, as Stephen King advocates, “kill our darlings”.

I know I’m guilty of all these things. And, unless used judiciously, these four things (and many others) reduce the quality of the technical documentation that we produce.

If we want to produce technical writing that truly helps and guides our readers, it needs to be better. But, like any craft that we want to improve at, learning to write well takes time, training, and practice. It’s something that very few of us are born with.

So You Need to Have Tools

So we need to have tools that help us improve; holding our hand and guiding us in the right direction. 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!

To be more specific, it applies a series of checks to strings and text files, linting them for words that weaken their effectiveness.

These are:

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 previously, write-good uses a glob to identify the files to lint, then scans them, and finally prints its suggestions to STDOUT.

Let’s step through an introductory example, where I’ll lint all the AsciiDoc files in some technical documentation that I’m working on at the moment. I’ll start by passing a glob of AsciiDoc files to write-good.

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

And below you can see an example of the output that results. While not the clearest to read, the output below shows three, specific, things; it:

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

The output’s helpful, but it’s not that readable for us mere mortals. Let’s make the output easier to read by using the --parse option, as in the example below.

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

Using this option makes the output (in the example below) far more readable. Wouldn’t you agree? It also makes it easier to pipe to other tools, such as grep, sed, and awk.

# 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, quickly, see that it prints:

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

How To Enable Only Select Checks

By default, when write-good is run, it runs all its checks. However, it’s best to start off gently if:

1. You’re just beginning your journey toward writing strong technical documentation.
2. You’re just getting started with an old documentation base, one that saw better days.

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 next example, we’re going to activate just one rule. I’m a big writer of ‘so’, so (heh) I’m only going to enable write-good’s so check. 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 actually had to drastically alter the glob to find the single file where “so” was used, which you can see below. As before, you can see the file, line, character, occurrence of “so”, and why it’s considered unhelpful.

Now, let’s deactivate several checks. Specifically, we’re going to deactivate weasel, adverb, and cliche checks. 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, and enabling or disabling specific checks, 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 first though, if only for me; 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 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.

CC Image Courtesy of Regina Yi on Flickr.

## Other Parts In This Series

• Validate Your Markdown files with MarkdownLint
• Easily Find Broken Links With Broken Link Checker
• Make Sure You’re Technical Documentation’s Always Professional With Proselint