Adobe DITA World 2018
Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

Stitcher radio

Search results

Adobe DITA World 2018

Is Premium Grammarly worth it for identifying style and grammar issues in tech docs?

by Tom Johnson on Dec 28, 2018
categories: writing

I recently ran every page of my API doc site through Grammarly to identify and correct style and grammar issues. Grammarly provides a lot of valuable feedback that is worth considering as you edit your writing. However, the issues flagged are more helpful for conceptual and narrative information rather than for technical procedures, in part due to the restricted vocabulary, unique tech terms, and more frequent passive voice in tech docs. Also, data privacy issues probably prevent Grammarly from gaining more traction in the enterprise.

The need for Grammarly

These past few weeks, I’ve been trying to finalize the content in my API documentation site to publish it as a Kindle book. First, I walked through every tutorial to make sure the steps were accurate and up to date. Given how rapidly tools and technologies change, I had to make significant updates. Next, I went through each page and pasted it into Grammarly to check for typos and style issues. Keep in mind that this API doc course, when printed to PDF, spans about 500 pages, so both of these tasks were not trivial. This editing took me weeks.

Although I’ve used Grammarly on and off to check documents and blog posts over the years, this month I decided to upgrade my subscription to the Premium version so that I could see all the issues Grammarly flags. Is the Premium version of Grammarly worth it? Maybe for extensive writing projects, though I’m not sure for tech docs. I’ll give you a better sense of Grammarly’s style checking capabilities later in this post.

Side note: In case you haven’t noticed, I’ve been reluctant to write much about grammar on my site. I feel that the focus on the cosmetics of language often reduces the role of technical writing to wordsmithing only. In my view, writing is about 90% ideas/content and only 10% language. When people fixate on typos, to me it signals a lower-level analytical ability. There are usually much more significant issues to focus on (such as organization, structure, logic, support, flow, relevance, and so on) than grammar.

That said, one typo within a beautiful piece of writing will distract readers. A teacher once told me that having a typo in your sentences is like showing up to a party wearing a tuxedo and not realizing your fly is down. As professional writers, we should at least deliver grammatically correct, typo-free content. Never mind if it’s accurate or well-written. Just please let there not be any typos.

Grammarly not only checks for typos but also checks for style as well, which includes areas such as clarity, variety, concision, confidence, and so on. As style checkers go, it’s probably one of the best available. Although I feel pretty confident in my grammar knowledge, Grammarly helped me identify some consistent style issues in my writing, such as starting sentences with “This …” and over-using the words “simply” and “actually.”

Grammarly

Sample problematic sentences to plug into Grammarly

To get a feel for what Grammarly identifies as style issues, download the Grammarly app and copy the following sentences (which are all problematic in some way), and paste them into the app. Then look at the issues it identifies.

When you run content through Grammarly, you’ll see that Grammarly categorizes issues into the following groups:

  • Spelling
  • Grammar
  • Punctuation
  • Fluency
  • Conventions
  • Conciseness
  • Formality
  • Confidence
  • Clarity
  • Variety
  • Vocabulary

One sentence might have a misspelling, so it would appear under Spelling. If the same sentence has clarity issues, you’ll see the same sentence under Clarity too (with the clarity issues flagged rather than the spelling issues). More pressing issues are underlined in red, while optional fixes are underlined in yellow.

After checking so many pages, I noticed that I overuse the following words:

  • simply
  • actually
  • a number of
  • starts out
  • larger
  • great
  • good
  • in order to
  • definitely
  • absolutely
  • huge
  • especially
  • basic
  • bad
  • extremely
  • key
  • separate out
  • easier
  • important
  • complex
  • originally
  • constantly
  • own

Grammarly flags these words for a variety of issues: the words are overused, they’re unnecessary and contribute to wordiness, they don’t fit the context, they’re redundant, or for other reasons.

I also commit these grammar errors regularly:

  • Putting commas before “since” or “because”
  • Starting sentences with “This” (unclear antecedents)
  • Using passive voice (lots of “be” verbs)
  • Incorrectly phrasing “Not only … but also” constructions

Grammarly doesn’t explicitly say a sentence is wrong — it flags issues so you can examine them and check for yourself. You can expand an ellipsis in the Grammarly editor to read an explanation of the grammar principle. For example, Grammarly flags split infinitives but doesn’t say splitting an infinitive is wrong; instead, it explains that some readers might be put off by seeing an infinitive split unnecessarily.

Coming back to my original question — is Grammarly Premium worth it? Is it worth the price of two Starbucks Frappuccinos a month? As I’ve been working heads-down on editing, I’d say for sure! Grammarly has caught hundreds of errors or style issues that I’ve fixed. Take a look at these commit logs:

The file diffs show the corrections I’ve made. Surely, a tool like this should be in every writer’s pocket. But is it worth $140 a year? If you write a lot, yes. But recognize that Grammarly is more helpful with narrative and conceptual information. With procedural writing genres, such as technical documentation, I’ve learned to ignore most of Grammarly’s flags in the Variety and Vocabulary categories. If you use the same word too often, Grammarly suggests you change it up a bit for the sake of variety. But in technical writing, swapping in synonyms for the same word is a no-no. But the other categories (especially Spelling, Punctuation, and Grammar) are generally helpful.

Fixing passive voice (flagged in the Clarity category) will probably involve the most revision, and you can decide whether the effort is worth it. In many tech comm contexts, passive voice is acceptable because you don’t want to draw attention to the actor or subject. Even so, I was surprised to see so many instances of passive voice in my writing. Even so, seeing so many instances of passive voice in my writing surprised me.

Grammarly has also made me realize that I overuse certain words. I had no idea I was using the word “simply” and “actually” so much. While there are cases where these words might be warranted, I’m surprised how frequently they appear in my API documentation site. I’ve removed many of them. I also found that I use “a number of” almost as much, and “just” and “This …” and so on. I was also unaware that “main” and “constantly” and “originally” and “key” are overused terms.

Sometimes I found that I needed to consult the grammar principle. For example, should “usually” and “generally” always be followed by commas, even in short sentences? Is “in fact” unnecessarily wordy? When should intercepting clauses not contain the first comma (such as right after a coordinating conjunction)? And so on. I like that Grammarly integrates grammar instruction right next to the sentences it flags.

One other cool feature of Grammarly Premium is the ability to add words to its dictionary. Over time, this can help limit the many false positives flagged in the Spelling category.

My verdict about Grammarly in tech comm situations is that yes, it is worth it, especially if you can get your work to pay for it. However, there is a data privacy issue with Grammarly’s SaaS model that will likely be a showstopper in the enterprise.

Data privacy

Grammarly sends the content to its servers via API calls (I assume) for analysis and then returns content with the annotations. Most enterprise companies have security policies that prohibit this kind of data leakage. The following startling clause also appears in Grammarly’s Terms of Service:

By uploading or entering any User Content, you give Grammarly (and those it works with) a nonexclusive, worldwide, royalty-free and fully-paid, transferable and sublicensable, perpetual, and irrevocable license to copy, store and use your User Content (and, if you are an Authorized User, your Enterprise Subscriber’s User Content) in connection with the provision of the Software and the Services and to improve the algorithms underlying the Software and the Services.

There’s a lengthy thread on Hackernews about Grammarly — see Grammarly shared its tokens with all websites. Some concerns are that Grammarly could potentially act as a keylogger that is mining your text for keywords, which it could then feed to Internet advertising or some other service (though I don’t think there’s any evidence of that, as it would put Grammarly into a malicious category). Some people in the thread note alternative tools, such as Languagetool’s Microsoft Word add-on, but in my brief test, the grammar flags were weak in comparison to Grammarly. For more on the data privacy issue, see A Tiny Little Privacy Hack for Grammarly.

So while Grammarly seems useful for writers, it probably won’t take off in the enterprise. Without enterprise support, there probably won’t be much demand for such an expensive style checker ($140/year) given that most technical writers exhaust their writing energies at work and have only small creative bandwidth outside of work. I probably blog more than most, and I’m on the fence about whether a premium subscription is worth it.

For style checkers at work, some are more appropriate to tech comm, such as HyperSTE (which is a site sponsor) and Acrolinx (whose cost is usually prohibitive for small companies). Even Microsoft Word’s built-in spellchecker is probably a decent alternative to Grammarly.

In some ways, the ban of tools like Grammarly (and other similar ones such as Ginger, Grammarbase, etc.) mean that engineers and others who write important content in the enterprise will be more dependent on technical writers to edit their content, essentially serving as a human proofreaders.

Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 4,500+ subscribers

follow us in feedly