WordPress Tip: WordPress’ Biggest Mistake

WordPress's Biggest Mistake

WordPress's Biggest Mistake

For a company that recently secured $29 million in funding, has grown from nonexistence to worldwide popularity in just four years, and which has the reputation of being the platform for serious bloggers, it’s kind of bold for me to call attention to its biggest mistake in a post. But I’m convinced that it’s a huge miscalculation on the part of Automattic (the company that leads WordPress). The Automattic team, led by Matt Mullenweg, has about 25 engineers and …. not one technical writer.

In the engineer’s mind, writers are unnecessary because the code is so obvious. And WordPress even prides itself with its mission statement:

Through WordPress we’ve enabled millions of people to effortlessly publish to the web. Now we want to enable millions more.

“Effortlessly”? Excuse me, Matt should come over and watch my wife try to update something in her blog’s design. When the image don’t automatically float right or left to wrap around the text, when she wants to change her header’s banner, or limit the number of posts that show up in a category, she starts cursing WordPress under her breath.

My wife, who writes under the pen name “Jane,” is actually technically competent. She can edit and publish videos on Vimeo and Youtube, create linked image buttons for her sidebar, and resize and edit photos in Photoshop and Picasa pretty easily. But every time she wants to make slight adjustments to her blog … well, let’s just say last time she ended up throwing the mouse at me while I ducked near the kitchen microwave. Other times she literally pulls on her hair in desperation and says she’s “going to Blogger.” Swearing is also common.

The WordPress team overlooks an official technical writer and assumes everyone will update the WordPress Codex with the necessary documentation. Sure. Just like people will come out of their homes and automatically pick up the trash on the streets. If you’ve ever looked through the Codex for something, navigation is akin to backcountry hiking without a map. At least a quarter of the content is outdated. Much of the writing isn’t very task-oriented or clear to novices. It frequently resembles developer-writing, and screenshots are usually absent.

With the $29 million in funding WordPress has received, you’d think they’d at least pay an intern somewhere $20 an hour to update the Codex. Better yet, find someone with gusto and expertise like Lorelle to devote herself full-time to Codex upkeep. WordPress documentation is only getting worse. Is there not at least a 100 page manual that you can download (rather than buying a third-party book from Amazon)?

In the end, Blogger has much more marketshare because it’s an easier platform. WordPress could be more competitive in the marketplace if they simply hired a full-time technical writer to — I know this is shocking — add an online help file directly inside the application.

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

33 thoughts on “WordPress Tip: WordPress’ Biggest Mistake

  1. Rhonda

    Go for it, Tom! 😉

    And don’t forget, it’s not just WordPress… There are plenty of software companies out there who have large development teams but perhaps one or two tech writers (or none).

    I’ve always been gobsmacked by “The 20-member development team has been working really hard on the new release for 6 months and we’ve totally redesigned it. We release in 3 weeks and now we need the manual updated.” When there’s just one of you to interpret some 180 months of work (20 x 6 months) and write a brand new manual in just 3 weeks, they wonder why we roll our eyes and run screaming from the building.

    I feel your pain.

    Rhondas last blog post..Were you born before 1960?

  2. Pingback: Foul Writer’s World - Documentation 2.0

  3. w0

    1) blogger is an awesome platform, don’t knock it on any level. But just like WP, once you want to start tweaking a lot of stuff, you actually get wound up in technical details. Consider: what kind of person would use WordPress + NextGen gallery and what kind of person would use Blogger + Flickr.

    2) You are completely right that even a part time TW at some ridiculously low rate would add incredible value to a group creating a user-oriented piece of software.

    3) What WP needs is a TW / technical editor. There’s a perception that all the information is out there, and coupled with responsive forums, why would you need anyone to duplicate “and pretty-up” the writing when google can find it all?

    It takes only a few moments to think about users and how they find information to the conclusion that in more cases than not, you need an editor to arrange content in a highly usable fashion. BUT – this runs contrary to the wisdom of the internet, where we’ll create a piece of software to circumnavigate the editor role: THE WIKI – everyone is a technical writer and advanced search algorithms render any structure unimportant.

    I always felt that the codex had a few well-ordered entries, but overall had no beginning and no end. Some people may like this. I on the other hand do not find it usable.

    w0s last blog post..Firefox 3 adoption rate and the culture of the Internet

  4. Craig

    That’s one of the many reasons I’m still at blogger.

    Blogger is an easier platform. Once I got into nitty-gritty details such trying to see how many people were visiting and how many were regular subscribers, things got a little difficult, but I nailed it on the second or third try.

    I recently had over 300 unique visitors and I have 23 regular subscribers, according to google analytics. Not bad, to my thinking.

    By the way, this text is being typed into notepad and then copied and into the message box. Firefox really dislikes the textbox portion of your site. Thought you should know.

  5. Ted

    Some of you younger and more energetic folks ought to think about starting up a WordPress Help Writers group to tackle some of the low-hanging fruit head-on (and mix some metaphors). I run a few sites on WordPress and I like it a lot, but on my average interaction with it (not counting routine blog posts) I seem to spend 40 to 60 percent of my time hassling with information issues.

  6. Paul

    I totally agree with this post. I’m trying to help some friends use WordPress as a CMS for their sites, and it turns out it is really hard for average users to use. They can write posts and stuff, but any kind of complex editing throws them for a loop. And there isn’t help available.

    This seems to be getting worse with the latest developments of WordPress. Complexity is making things harder…

    Pauls last blog post..Cuil — not that cool, for me at least

  7. Lyndon

    As much as I love WordPress, just switched about a month ago from Blogger. The whole 5 minute install thing, is one of the biggest lies ever! Thankfully I had a good host, who wasn’t using Fantastico to do installs. Or I would have been stuck in limbo like so many users.

    Tweaking things on your template, can be a pain in the ass too! I miss the simplicity of blogger on those things. The wordpress team could definitely do a lot of improvements to hopefully solve the problem.

  8. mpb

    I have always been struck by the absence of empathy towards human factors/users and usability. Often doodads have been added because they look snazzy but very little has been done to improve the editing and writing by the user. Dark grey text on very dark grey background doesn’t work. Snap-views interfere with users; poor search ability.

    I guess I should be proud that my comments on Matt’s posts about the latest “surprise” are blocked.

    But seriously, WordPress.com platform has great potential for authentic discussions and reaching out to disadvantaged communities. I just wish they let an anthropologist at the interface, along with the tech writers. [as a trained archaeologist, I’m very good at breaking things, especially assumptions about systems that involve people interacting in space and time.]

  9. Scott

    Is it just me, or have a few things become a bit more difficult in the last couple of point releases of WordPress? Take, for example, inserting images into a post. It used to be a lot easier. Now, I have to go through a couple of more steps, and then do some manual tweaking to get the image into the right position in relation to text.

    And the very AJAX-y look and feel to the WordPress admin interface really does nothing for me. Makes me yearn for the simplicity of an older version of WP, or the Blogger interface (not that I’m switching back).

  10. Tom Johnson

    Ted, re the WordPress Help Writers group you suggested, there is already a WordPress Codex Documentation group. The problem is that writing documentation is not nearly as appealing as creating plugins. I’m not entirely sure why. I’m sure I should contribute to the project in the best way I can; I just don’t feel compelled to do it. Seems too much volunteer-like. Maybe that time will come some day, perhaps if I had to spend an entire summer in the hospital or something.

    I did start a small WordPress online help file that I posted in the lower-right corner of my site.

  11. Tom

    Paul, I recently created a website for a guy using WordPress, arguing that it would be easier for him to maintain, to edit, etc. He’s more used to Dreamweaver and finds many of the WordPress concepts unfamiliar, so my plan actually backfired. Also, even though much of WordPress seems intuitive and push-button, we have to remember who we are — web savvy technical writers. For the masses, it’s still web design and web publishing. People who don’t even understand FTP will have trouble.

  12. Tom


    The 2.5 release of WordPress was mostly an attempt to make the user interface more intuitive and easy to use. It was an entire reskinning. They also introduced the gallery features and the Add Media buttons. The Image Alignment button on the web editor toolbar had some quirks with it. I’m not entirely sure what was going on, but it didn’t work right.

    In 2.6 they took away the Image Alignment button entirely (without mentioning it in their release notes). It was just gone. They left only the Add Media buttons. Now when you click an image, it seems like you can easily select the alignment.

    BUT, they forgot to tell you something important. The Add Media buttons apply a class to the images in your post. They don’t format the image with inline formatting. So if you don’t have the right classes in your blog’s stylesheet, your images won’t wrap correctly when you publish your post.

    I believe the essential image classes are as follows:

    .alignleft {float:left}
    .alignright {float:right}
    .centered {display:block; margin-left:auto; margin-right:auto}

    If you look in the default theme, its stylesheet has the correct image classes. However, I’ve had some trouble getting them to work with some themes. It’s not just as simple as pasting them in at the bottom of your stylesheet. Look how your theme currently styles images, and tweak the classes for those image styles.

    Another new feature is image captions. If you look in the default theme’s stylesheet, it has the correct image captions, and they look awesome. However, I haven’t been able to get these to work in my theme yet. I’m not quite sure what I’m doing wrong, but I haven’t played around with it too long.

    The absence of this kind of communication — like hey, we’re no longer styling images with inline formatting, but rather applying a class that you must have in your theme’s stylesheet — is part of the lack of instructions that I think the WordPress team needs to be more thorough about.

  13. Erika

    Found you by chance, adding you to my feeder. :)

    I’ve learned, after trying to teach a client how to use his newly-built WP-based CMS, that it IS moderately tricky for someone with little knowledge to make edits beyond text to their website. Yes, that WAS a surprise to me because after you have your hands in the code for so long, you become a little out-of-touch with how the gen-pop deals with certain issues. I wound up writing an entire co-manual for him that, ironically, ends with “If you have ANY questions or problems, don’t hesitate to call.”

    The codex, however, is a pain in the tail. If you get deep enough into it, you’ll find language seemingly written by our ESL friends… even statements that question WP itself within it’s own codex. Really comforting, LOL.

    I do hope that they take the time to work on this stuff, though. I love WP and have managed to make my way around it’s occasional quirks, but it’s hard to explain it to clients who eventually give you the “eyebrow.” I’m sure you know what “eyebrow” I’m talking about. LOL.

    Erikas last blog post..Miami Web Design

  14. stubsy

    I have never actually had a problem with wordpress myself I never read instructions for anything anyway.

    There are plenty of blogs about blogging and wordpress about so you can nearly always find the answer to your problems in Google.

    stubsys last blog post..Make money from new sites

  15. Whitney

    You’ve hit a nerve with me.

    If WordPress is so easy, why is there a huge cottage industry of independent geeks and pros who do nothing but set up, extend, and troubleshoot WordPress for everyone else? If it’s so easy, how come some of these people get away, repeatedly, with charging folks $400 or more just to upgrade someone else’s WordPress blog to 2.5?

    Because it’s NOT.

    I’m like your wife. I’m technically competent. I can replace a motherboard, install a second internal hard drive, set up a wireless network, put up a Web site, even do a little JavaScript (even though I hate it). I can do most anything with GOOD DOCUMENTATION.

    I find standalone WordPress to be obtuse. The so-called documentation makes it worse. And the scads of WP Plug-ins make it difficult to tell what you need, at minimum, unless you want to make learning about WordPress your new hobby. Which I don’t. And I don’t want to learn PHP, either, for the occasional updates I’d make…so infrequent that I’d have relearn PHP every time I needed to do something with it.

    I’ve worked with Blogger. It’s okay. I’ve run into things I don’t like, but I know there’s people who LOVE Blogger so I’ll keep my comments to myself. I run another blog on TypePad and love it (and their DOCUMENTATION). Every time I need to do something with WP, I love TypePad more and wish that when I’d started my blog, I’d just gone with TypePad instead.

    The WP documentation needs to be better, as does much of the documentation for plug-ins. Much as I want to see better documentation, I agree with you, Tom. The level of effort that would be required at this point is far more than anyone should be asked (or expected) to do for free as a volunteer effort. If they’ve got $29 million in funding, they can damn well afford a couple of technical writers.

  16. Pingback: The Myth of Simplicity and Complexity in Help Authoring | I'd Rather Be Writing - Tom Johnson

  17. Pingback: Thank You Silahsiz Kuvvetler for Showing Me the Light | I'd Rather Be Writing - Tom Johnson

  18. Janet

    I use WordPress, and I agree, too. I’ve gotten the impression that some of the WP gurus take the attitude that they’re geeks, they’re giving the rest of us their cool software, and if we have a problem, it’s our problem. They not only know how to work around the problems, but they also enjoy doing so. Fine for them, I guess. Sometimes I wish they’d do a little more to commercialize it so that good documentation would be expected, and updates wouldn’t be released until they actually work as “advertised.”

    Janets last blog post..Papalo at home among beans and hot peppers

  19. Pingback: Some Organizations STILL Don’t Get It : Connected Content

  20. Marc Norris

    I would say that WordPress does have its challenges, but honestly, it beats the old days of creating a site page by page in HTML.

    If you do have self-hosted WordPress blogs, I would suggest that you make your life easier by using some of the desktop blogging software (such as Windows Live Writer) that makes aligning images, spellchecking, and links that much easier to work with.

    Marc Norriss last blog post..Back to Basics

  21. Pingback:   The cottage industry of supplementary documentation by Communications from DMN

  22. Shaun Carter

    I don’t think WordPress management knows what they want their flagship product to become. I don’t understand why they rely on the userbase to support the product for the most part while they find more funding for a non-profitable product.

    Shaun Carters last blog post..Get $50 From Trade King

  23. backlinks

    First of all congratulation for such a great site. I learned a lot reading article here today. I will make sure i visit this site once a day so i can laern more.

  24. WordPressAddict

    I could not agree more.

    The Codex is very confusing, especially to new users. It doesn’t have clear separation between information for beginning or casual users and information for advanced users (read: willing to dive into PHP). And it has many, many outdated entries, or entries that have so little information that they seem deliberately cryptic.

    The two WordPress manuals that have been published in print are really only marginally useful for beginners, and not very useful at all for those seeking to customized WP in advanced ways, but without a programming background.

    In short — out of the box, WordPress is easy to use, if you don’t plan to customize it much. But if you want to customize… well, it’s like those old maps that had “Here Be Draggones” — you’re on your own. On the other hand, the great appeal of WordPress is that you *can* customize so much, if you’re willing to climb an often very steep learning curve….

    1. Tom

      WordPress Addict, there was a recent discussion on the wp-docs mailing list about an alternate method for creating the documentation. I’m wondering if you have any ideas on how they could improve, e.g., what new method they might use. I suggested hiring a professional technical writer to manage the documentation, but right now it looks like that’s still a developing role. WordPress does have a lot more screencasts now, and I believe the guy who creates the release notes screencasts is full time with them. Matt mentioned an upcoming effort to integrate the screencasts within the admin interface. The problem, though, is that the really tough stuff is in the php code snippets scattered throughout the forums.


Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>