What technical writers can learn from a WordPress plugin

I’m evaluating WordPress plugins for our STC chapter’s web site migration. I use WordPress for edmarsh.com, but the requirements for a personal blog as opposed to a full-on web site – particularly plugins – are quite different.

The Yoast SEO WordPress plugin's keyword tab shows writers how their content compares to other sites using the selected keyword
The Yoast SEO WordPress plugin’s keyword tab shows writers how their content compares to other sites using the selected keyword

A post recently appeared on Facebook, advertising the 57 best WordPress plugins. The list felt a bit too self-promotional, but there were some good selections, and I implemented a few. The very first plugin on the list, Yoast SEO, changed the way I feel about writing, particularly for the web.

What does the Yoast SEO WordPress plugin do?

Yoast SEO plugin shows you how your page rating in your Publish settings
Yoast SEO plugin shows your page rating in your Publish settings, as well as in the Administration banner

Search Engine Optimization, or SEO, is a term long associated with derision. Some (like me, in 2009) think SEO consultants are a bunch of scammers trying to guarantee your site will automatically reach the top-10 in Google (it won’t). I installed this plugin on edmarsh.com to see what it would do for my content, and while I still don’t trust SEO consultants, the results surprised me.

Yoast came with a new term for me, called the 1Mil/1K Club, where a plugin has 1 million installations and 1000 5-star ratings.

Once installed, a new section appears on all the post and page creation pages within WordPress. Two icons appear in the Publish section of the page; another appears in the Administration header. A whole new section appears below your text entry field. Two tabs – one for readability and one for SEO – help you identify issues with green/yellow/red icons. An eye icon appears next to the issues that it can highlight in your text, such as passive voice usage.

Why I now think differently about technical writing

I first pointed Yoast to my About page.  The plugin quickly illustrated how poorly organized the page was to achieve my goals, which is to tell people what I do. Yoast showed that the About page didn’t say anything about me if it came up in search results. It also indicated I should use more headings to break up the text, and ensure there aren’t too many words per heading.

I found the “Snippet preview” on the Keyword tab helpful for the first sentence. This preview displays what users will see on Google when searching. It is also helpful for creating the short bursts of text that Twitter requires, which are automatically sent by another WordPress plugin.

The Yoast SEO plugin snippet preview shows you how your post appears on Google.
The Yoast SEO plugin snippet preview shows you how your post appears on Google. Using Yoast, you can customize how the results appear.

I then copied and pasted some of the recent blog posts from the STC NY Metro site to my WordPress development site. On both content and SEO, all of the results came up poor. This was surprising and a bit disappointing, as they were written by professional technical writers and edited by our newsletter team (including me!).

I thought we were doing a pretty good job delighting our customers with content, but this plugin disagreed.

Summing up Yoast SEO

We live in a Google world. Considering search in your technical writing will make your writing tighter, and ensure the most relevant topics are returned to your users. If you’re in a WordPress environment, the Yoast SEO WordPress plugin will help you do that.

Yes, technical writing is different than web writing, but there are some things to learn from using this plugin. Just like having a structure for your content, that additional check allows you to really think about the quality of the content and how your readers use it. When creating a style guide for the new STC NY site, we’ll instruct our authors to review the SEO plugin before they’re published.

Yoast SEO WordPress plugin Readability tab
The Yoast SEO Readability tab shows writers where their content needs work

However, consider that these are automated suggestions. I certainly haven’t followed every single suggestion; some are frankly awkward. The focus keyword on the keyword tab doesn’t consider plurals as part of the focus keyword. But using Yoast, I now think differently about how I write, both in my work and my blog.

The downside? Continually re-crafting your writing and blog posts. I’m at revision 33 34 35 46 already. Prior to installing the Yoast SEO plugin, most of my blog posts had fewer than a dozen revisions!

What do you think about technical writing and tools like Yoast SEO?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.