Why WordPress Core Needs a Writing Style Guide

Update: We’ve published the results of our survey on the tone of WordPress Core. Please have a look!

Tone is often a subliminal thing. Over months and years, you work with a person, an organization, or a software package, and eventually you notice that it generally makes you feel either happy or bummed out, listened to or scoffed at.

I wrote this post after noticing that parts of my daily interactions with WordPress Core were making me feel the wrong sets of things. The post outlines what I believe to be significant problems with the written tone of WordPress Core, and argues for the creation of a formal WordPress writing style guide.

To describe the principles I think WordPress currently drifts from, I’ll be using advice from two existing style guides:

1. Voice and Tone, the official style guide for MailChimp, specifically its section on writing error messages.
2. The classic general-purpose style guide The Elements of Style—specifically, Rule 9 from the guide: Do not affect a breezy manner.

“Breezy” here means smug and tossed-off. We’ll return to this below.

Problem 1: Sarcastic error messages

Style and Tone has these suggestions for writing error messages (which it calls “failure messages”):

1. Be straightforward. Explain what’s going on right away.
2. Be calm. Don’t use exclamation points or alarming words like “alert” or “immediately.”
3. Be serious. Don’t joke around with frustrated people.
4. If possible, offer a solution or next step.

WordPress fails at points 1, 3, and 4 at various times, but point 3 is the one I want to yell through a megaphone.

The worst offender:

I find the “Are you sure you want to do this? Please try again.” error message to be one of the most off-putting things in all of WordPress. It reads like a caption for the Hipster Barista meme, so I’ll just let him stare at us for the rest of this section to give a sense of ambiance.This message provides no information of any kind, and vaguely blames the error on the user’s stupidity. “Are you sure you want to do this?” also contradicts “Please try again.” so fiercely that it almost has a kind of comedic grace—if only it wasn’t the way WordPress chooses to tell you that you’ve just lost your post edits.

On that note, I often see this error message as a one-off when I try to save a post or do something equally innocent. It’s not like I’m nuking template files, not that the sneering attitude would be justified even if I were.

The tone on display here most likely reflects a tossed-off joke, designed to replace a generic error message like “We’re sorry, something went wrong.” Fair enough, but then again, Don’t joke around with frustrated people. We are indeed sure we want to save our post, thanks, and if you don’t know why that’s not working at the moment, just say so.

The default 404 message

The WordPress default 404 error message, likely present on most WordPress sites, is: “This is somewhat embarrassing, isn’t it? It seems we can’t find what you’re looking for. Perhaps searching can help.”

Do not affect a breezy manner, and Don’t joke around with frustrated people. When your users see this error message, they will assume you wrote it. If they’re anything like me, they’ll wonder why you find it so funny that your site is missing content, has a defective navigation menu, lost their purchase, etc.

This error message also fails to explain the error itself; such an explanation would read something like, “We’re sorry, no content was found at the address you specified (HTTP error 404).” Non-technical people may not know why the site “can’t find” what they’re “looking for” (“So it’s there, but you couldn’t find it? There’s something wrong with the way your site finds things?”), or what to do about it if searching doesn’t, in fact, help.

When software breaks, it should not impose an imaginary shared experience of embarrassment on the user.

When software breaks, it should not impose emotions, like an imaginary shared experience of embarrassment, on the user. It should explain what went wrong in as much detail as is helpful, and alert the user to any resources that may help address the problem.

Problem 2: A smug and tossed-off overall tone

The power of words is foundational to the mission of WordPress—in fact, it’s right there in the title.

You definitely wouldn’t know that by WordPress’s default content.

Hi there! I’m a bike messenger by day, aspiring actor by night, and this is my blog. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin’ caught in the rain.)

…or how about,

The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community.

In my opinion, this kind of casual, trivial writing (and the Hello Dolly plugin, the comment by “Mr. WordPress,” etc.) makes WordPress seem cheap and trivial as well. At the very least, after years of seeing it, it makes me wish for a “delete everything WordPress wrote” button when I do a new install.

Just for reference, here’s an excerpt from the beginning of the children’s book The Little Prince that treats words with care:

I showed my masterpiece to the grown-ups, and asked them whether the drawing frightened them.

But they answered: “Frighten? Why should any one be frightened by a hat?”

My drawing was not a picture of a hat. It was a picture of a boa constrictor digesting an elephant. But since the grown-ups were not able to understand it, I made another drawing: I drew the inside of a boa constrictor, so that the grown-ups could see it clearly. They always need to have things explained.

The millions of people who see this content should come away with the sense that words, and WordPress, are more than a tool to make cheap jokes.

That’s fun! How about something like that for sample content? Or a prosified Shakespeare soliloquy, or the opening lines of a beautifully written, non-controversial, public-domain novel? Even revising the current content to be carefully and maturely written would be an improvement.

The point is that the millions upon millions of people who see this content should come away with the sense that words, and WordPress, are more than a tool to make cheap jokes about aspiring actors. In my estimation, this is one of the easiest and most impactful things WordPress could change about itself.

Problem 3 (bonus): An install success message that causes sadness

When you get a WordPress.org install up and running, the message you get is: “Success! WordPress has been installed. Were you expecting more steps? Sorry to disappoint.”

Users who read this message will have just finished the following process:

Logging into their hosting account; creating or finding their FTP credentials; downloading and unzipping WordPress; uploading WordPress to their hosting account; creating a MySQL database and an associated database user with a secure password and appropriate permissions; getting wp-config-sample.php locally; copying the database name, database user, and password into wp-config-sample.php; copying and pasting the link in wp-config-sample.php into their browser to get hash values; copying and pasting the hash values back into wp-config-sample.php; setting a database table prefix; renaming wp-config-sample.php to wp-config.php; FTP uploading wp-config.php; deleting wp-config-sample.php; opening the root page of the URL associated with their hosting account; and entering a username, password (twice), and email address.

The message they’ll receive for completing this process with no errors will imply that it was so laughably simple that they probably feel a little let down. In my estimation, actual humans, particularly humans new to WordPress, are unlikely to get the joke. Do not affect a breezy manner.

Besides that, why go negative? You’ve just installed some of the greatest software on the planet—why mention disappointment at all? Why make a snarky joke, even if the joke happened to work? You never know who’s in the mood for Hipster Barista’s ironic praise—but a succinct, genuine welcome to the world of WordPress would never go out of style.

Concluding thoughts and recommendations

Where the problem comes from

I think I understand where each of the missteps described above came from: writing software is fun, and once you’ve got something up and running, it’s tempting to let your glee spill over into breezy, winking content. The cutesy “Too close for guns, I’m switching to missiles” of Thefacebook.com comes to mind, as does some self-satisfied PHP commenting in my own past (and perhaps future).

Why it’s a problem

One of WordPress’s greatest and most fixable weaknesses is its own use of words.

Like Facebook, WordPress is all grown up now; but unlike Facebook, its written content doesn’t reflect that maturity. One of WordPress’s greatest and most fixable weaknesses is its own use of words.

Words have power: power to define new users’ impression of the seriousness of WordPress and its creators; power to alleviate users’ frustration or aggravate it; power to provide information or smugly withhold it. WordPress’s current written content sporadically disregards that power, making WordPress seem like a cheaper, more irritating, and less well-executed project than it really is.

How to fix it

The WordPress core should get a content overhaul that follows a content plan. This would include:

1. Creating a formal writing style guide, very much like Voice and Tone, written and maintained by the WordPress community. This style guide would be used as the standard to evaluate and modify all written content—both to identify existing content in need of revision, and to guide the creation of new content.
2. Iteratively receiving feedback on all text content from users—new and experienced, all ages and ability levels—focusing on tone, comprehensibility, and helpfulness.
3. Establishing an open and systematic process to periodically review WordPress’s written content.

The overall written tone that gets baked into the style guide should be a discussion for the community, but here are my three cents:

1. WordPress’s written content doesn’t need to be devoid of humor (actually, I like MailChimp a lot for that), but it does need to transition fully out of the gee-whiz/ain’t-I-cool/ain’t-you-stupid school of garage software writing.
2. WordPress’s written content should abide by whatever good suggestions are to be found in existing style guides (like the ones referenced in this post).
3. WordPress’s written content should respect, and inspire respect for, the power of both WordPress and words themselves.

A lot of people believe in WordPress as the way for people to share words with the world. We can do more to unlock the power of that promise, starting with WordPress itself.