Why WordPress Core Needs a Writing Style Guide

WordPress This is somewhat embarrassing, isn't it?
Posted in Editorial

Thanks to our content partner!

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: are you sure you want to do this? please try again

are you sure you want to do this? | wordpress hipster baristaI 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

were you expecting more steps? sorry to disappoint | wordpress hipster baristaWhen 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.

57 Responses

Comments

  • What a brilliantly written post that hits the nail on the head of an issue that has also bugged us (maybe without really realising how much) for many years. Well thought out, well written with a well defined solution that would fix this

  • Chris says:

    These are some great ideas. You should get involved! http://make.wordpress.org

  • says:

    Excellent post, all the more surprising for being the first one to address an “invisible” or “low-priority” issue so clearly.

    I’d like to add, as a translator of WordPress, that

    it does need to transition fully out of the gee-whiz/ain’t-I-cool/ain’t-you-stupid school of garage software writing.

    should read, for all of us who are not from the US:

    it does need to transition fully out of the american gee-whiz/ain’t-I-cool/ain’t-you-stupid school of garage software writing.

    I have nothing at all against colloquialisms (or americans, for that matter), but limiting the style to a particular subculture of a particular country makes localization (and not just translation), incredibly hard. Each of our countries’ subcultures may not be divided along the same lines, for one, and any translation always ends up being either unnatural (and hence irrelevant) or, even worse, specific to a very limited group.

  • Patty says:

    Thank you so much for writing about this. Those WP error messages are most definitely irritating to me, and when my clients see them, just embarassing. I especially dislike the “breezy/smartass” tone.

    You didn’t mention “Cheatin’ uh?” That is really infuriating. I got it while doing something completely legitimate, and just wanted to punch the person who wrote it. I think it’s on an index page for some obscure directory.

    For me, the very worst of the worse is the WordPress.COM 404 message which you may find in your face due to a website having a bad link: “Easy, tiger. This is a 404 page. You are totally in the wrong place.” That is just unbelievably irritating, especially when you’ve done nothing wrong, and in fact, have no need to be calmed down or reprimanded by some snarky Automattic developer.

    Any chance this post will get read by WP core developers?

    • Kirk Wight says:

      The text one sees on a 404 error comes from a theme’s 404 template, so it varies with every theme (it’s not a WordPress project or WordPress.com service specific text). This means that theme authors are free to use whatever language style and tone they choose for any front-end messages.

      Honestly, I’m a little surprised the breezy tone is found in so many themes.

      • Patty says:

        That’s not accurate. WordPress.COM themes are all provided by Automattic, so the 404 page is always their responsibility. The other error message I mentioned (“Cheatin’ uh?”) is a part of the WordPress core.

  • Ed says:

    Very well said and hopefully will generate some change to a long neglected area of WP.

    Thank you Fred.

  • Ozh says:

    Excellent post. I’ve raised earlier that the “are you sure you want to do this” causes more problems than expected, but with not much luck :)

  • Fantastic post. A style guide is definitely needed. Like you say, WordPress has matured and the language that goes with it also needs to mature.

    • Ryan Hellyer says:

      My Mum told me I had to do a whole lot of things once I grew up. I’m now 34 and still don’t do any of those things :) Sometimes growing up is not needed, it’s just boring ;)

  • Ian Stewart says:

    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.”

    I’m pretty sure I wrote this. It was introduced to default themes in Twenty Eleven. It was probably in Toolbox first. So, likely at least my fault there. That said, I’ve always liked WordPress’ breezy, tossed-off tone, from commit messages, to error messages, to saying “Howdy” when you log in. I’m surprised it’s been as consistent as it has been given the number of contributors to bits and pieces.

    This is somewhat embarrassing, isn’t it? :)

    • Although it is an extremely small sample, you may be the only one that likes this style of writing ! As Z? said in an earlier comment, for anyone outside of the USA, it doesnt translate well to other countries (nobody in the UK or most other English speaking countries would EVER say “Howdy”, it is just cringeworthy!), let alone to other languages.

      Patty asked “Any chance this post will get read by WP core developers?” To which Andrew Nacin replied “Yes” so I guess a better question would have been “Do any of the WP core developers consider this long overdue for change ?”

    • Ryan Hellyer says:

      Despite the naysayers here, I actually think that’s an awesome piece of text. Thumbs up from me :)

  • Excellent breakdown of a real issue. This is something that needs to be done. The “are you sure you want to do this” message is the perfect example of software that is belittling its users.

  • Slavisa says:

    WOW, this was really interesting and shrewd :D
    I chuckled.

    Good job, Fred

  • Ben says:

    I read the whole article and agree but I’m curious about something else you said.

    When installing WordPress you edit wp-config by hand. Why? The install process does all that for you. Agreed that creating an ftp user and setting up ftp can be a challenge for some – but that’s all you need to do – assuming you’re not using one of those apps that does everything for you.

  • Matt says:

    WP has always been optionated software with a lot of personality. Every year or two people try to neuter it, remove a bt of its soul, and sometimes it gets through. There are always convincing reasons, like this post, but it’s sad nonetheless. If anyone is going to stop using the software over these we probably didn’t create something very compelling in the first place. You could also create a “dry” localization of the software and see if it gets much traction.

    • Patty says:

      But a lot of us don’t think that trying-to-be-funny/condescending/English-colloquial error messages are “soulful” at all. We like things that are soulful and have personality, but that’s not an excuse for messages that just sound dumb and embarassing, if not insulting.

    • WP is such good software that nobody is going to stop using it because of this ! However, how can looking to remove some of the worst condescending language and using American colloquialisms (which even many Americans cringe at !) be seen as removing a bit of its soul. It doesnt have to be dry, just less “howdy doody” and a bit more professional. There are any number of studies on best practice for things like this, and especially for 404 pages, most of them say dont make it appear that it is the visitors fault that they reached that page (because it generally isnt !)

    • Patty says:

      I think it would make more sense to have WordPress use simple, straightforward verbiage, and have people who like the howdy-embarrassin’-cheatin’ kind of language to create their own localized version.

    • Jacob Perl says:

      I think with WP’s phenomenal 20% adoption rate across the web, nobody is suggesting that people will stop using it because if this relatively trivial issue. But as compelling as any software may be, there should always be considered room for improvement. I like software to have humor, personality, and “soul” (whatever that may mean to different folks). What I don’t like are error messages that are completely unhelpful and on top of that give me that feeling of being kicked when I’m down. I also don’t like smug baristas. Does “soul” really make that necessary? Has it ever come close to making me not want to use WP? No way, Jose!

    • David Decker says:

      Sorry, Matt, but this kind of tone and such messages are not the “soul” of WordPress! This is ridiculous. It gets even worse, when people try to translate WordPress and knowingly or unknowingly reflect this tone in the translations. This ends up in a mess.

      WordPress should lead by example and offering a polished, neutral language – that does not confuse users and could – in the best way – also help translators.

      • Patrick says:

        I’m 100% with you. I’d like to add that I’d be very useful to have such style guide extended to translations too. My number one wish is that translations address the user in a formal way. That’s something the English speaking world has not to care about, e.g. ‘you’ can be used in a formal or informal way. But for instance in German or French the formal and informal languages are quite different.

  • Gerald says:

    Great article Fred.
    interesting topic I never really thought about in depth. I’m with you on the mature aspect, but it also gives WP some kind of personality. A workaround could be a plugin. I didn’t researched that but with according filters (if available) you could preset the messages. Maby with an option set “default” “serious” “gangsta”. On a brand new install you can quickly set wp into the required mood.

  • Fred Meyer Fred Meyer says:

    Thanks so much to everyone for the comments! It seems like my experiences are fairly widely held, so I’d like to try to help create the style guide and review system described in the post.

    If you’d like to be involved, please email me at fred@pressupinc.com; I’ll send updates and next steps as I have them. My current plan is to sit in on a couple of the weekly core development meetings to get a feel for how we can best approach this, and also possibly set up a sandbox where we can start to collaborate on a style guide.

    Also, if you have any recommendations for approaching this process (*especially* if you’ve contributed to core before), please get in touch!

    In response to Matt’s comment (nerd chills): I do think it’s possible to keep WordPress’s content interesting and colorful–it should just be in a consistent way that stays appropriate to what’s being communicated. I think MailChimp is a model for this, and their use of a style guide seems like a large part of the reason why they do it so well.

    • Patty says:

      Since you mention MailChimp – I think they do it pretty well too, show some humor and personality. But I know for certain that it fails with some people. I had to talk a client into it just this week; she first refused to use it, saying that “MailChimp is just too weird”. So even using a style guide and being careful about it isn’t necessarily enough to not lose business over insisting on “personality” in communications.

  • RW says:

    Awesome post. Totally agree. I would like to see the wordpress core branch towards better CMS and security. Too much bloat in the core in my opinion.

    • This thread has nothing at all to do with WP being a better CMS or being more secure (both of which WP is the best already) so if you cant offer a sensible contribution, then please dont bother !

      • RW says:

        HH, you’re right the thread didn’t talk about WP as a CMS or security, but it was about the WP core writing. So I thought I’d add my 2¢. I wasn’t trying to hijack the discussion.

        • OK so if you weren’t trying to hijack the discussion why raise the issues of “being a better CMS or having more security” that you did or in fact talk about bloat in WP, none of which are true or applicable to this discussion.

  • Ryan Hellyer says:

    I think some of you need to grow a funny bone. Having said that, the argument regarding translation problems is a legitimate one.

    • Funny? I guess you have a different sense of humour to me. This isn’t about whether the text is funny or not though, it’s about whether the text should be professional, clear and informative. As Fred illustrates in this article, there are a number of places where it isn’t professional, it isn’t clear, and it’s not informative.

      Maybe for the hobbyist and people running their own sites, the text is appropriate, but for those using WordPress for commercial development it’s a regular inconvenience that a few ‘fixes’ to the core could remove.

      Perhaps WordPress should come with two language packs – professional and ‘funny’.

      • Ryan Hellyer says:

        I don’t think it would need included by default as this seems very much like an edge case, but yeah, a new language pack for formal usage would make sense IMO.

        • @Roger – a good idea but with the “Professional” one being the default and maybe the current wording in WP being included as “Geek American Possibly Funny”

          @Ryan – it is far from a “edge case” and it doesnt even have to be formal / professional although that is an option but the default should be less geek

  • I just wanted to weigh in with some thoughts here.

    Strunk and White’s The Elements of Style is not the ideal touchstone for creating user interface text. I love that book and it’s certainly something that I look at while writing prose, but it was written in 1918, with no thought for how UIs work, nor to how society has changed. The “Don’t affect a breezy manner” clause from S&W is totally misplaced 100 years later. Writing evolves, interactions evolve.

    Besides, text in WordPress, or any piece of software, shouldn’t be construed as prose (S&W’s “don’t be breezy” applies to authorial voice), but as a character; software talks to the user. There are interactions between what the user does and what the software says. In fact, that’s something that you’ve done yourself with the WordPress-as-hipster thing. Mailchimp, as well, can be conceived of as a character.

    Conceive it this way: what type of character is WordPress? Perhaps that character is breezy, and that’s totally fine.

    If there are times when the content or error messages are overly snarky or annoying then we’re missing the mark, but rewriting all of the content according to The Elements of Style will remove something essential about what WordPress is. Any content that is overly confusing or snarky or falls out of line with WordPress’ character and could be revised. But at no point should WordPress lose its soul.

    A community-created style guide isn’t workable; style guides just can’t be created that way. Writing by committee is as bad (worse) as designing by committee. Lots of time is spent arguing over usage of words and by the time everyone has had their say the voice is diluted. A style guide would definitely be useful, but getting a committee together to do it isn’t the right approach.

    the docs team discussed this at our chat on Thursday: http://irclogs.wordpress.org/chanlog.php?channel=wordpress-sfd&day=2014-03-14&sort=asc#m94608 We’ll likely discuss it next week – feel free to come along and join in the chat.

    • Absolutely. I’ve worked with people who *think* they know how to write and want to tell someone who DOES know how to write how to go about it. (I’m a qualified journalist). A style guide is dead easy to write, I’ve written them. You don’t need twenty people all weighing in with their two penn’orth (colloquial Britishism there).

      What WordPress should do is hire the odd professional writer from time to time, not people who think they are writers because they have blogs.

  • Chuck says:

    Shouldn’t there just be a plugin that allows all the verbiage like that to be edited in one spot?
    Language pack?
    Themes for languages?

  • Just to acknowledge and give another thumbs up to this piece. Oh, and to also mention “cheatin ‘uh” and “hello dolly” as other bugbears.

    Have lost count of the number of times I’ve had to apologise for or explain WordPress’s text to clients.

  • Fred Meyer Fred Meyer says:

    Hi everyone,

    Thanks so much for all the thoughts. We’ve started a survey on the written content in WordPress core. Please have a look! The survey will be open until April 4.

  • Joe says:

    I agree with much of this, and this issue is one reason of several why i steer clients away from WordPress anymore. The solution is simple… use Joomla! ;-)

Pingbacks

Add a comment

(required)

(required)

(optional)