Software, Development, and WordPress

The Importance of Using Domain Language in WordPress

In building software – especially at the enterprise level – one phrase that’s used to describe the work that goes into understanding what all needs to make up an application is that of the “problem space” or the “problem domain.”

This is important because part of the process of understanding the problem domain is learning the language, the terminology, and the concepts that go into building an application.

For example, say you’re building a job board. You’re likely to have something like:

  • Job Posts
  • Resumes
  • Recruiters
  • Employers
  • Employees
  • Candidates
  • …and so on

These ideas are then taken and ultimately converted into code.

Sometimes, developers will use the terminology associated with the problem domain (and this is part of domain-driven design) in their code; other times, the problem may get solved but the code may not completely reflect the problem space at the code level.

At any rate, one of the things that I see – as designers and/or developers – doing is using terminology that is more frequently associated with how we view WordPress than how users do.

The Facets of the Domain Language

First, the entire idea behind this post is to urge us to do a better job as using the terminology associated with WordPress as users and customers do, and not the other way around.

By that, I mean that when we’re writing articles, giving presentations, and talking about WordPress to users and customers, we need to make sure that we’re using the terminology that they see used throughout the application and the documentation – not the terminology that we use.

"What does that even mean?" They ask.

“What does that even mean?” They ask.

For example, I often see more advanced users – that is, developers, designers, and other similar people – using terms such as “The WordPress Admin” or “Taxonomies” or “TinyMCE” but to our users, this is jargon.

And I’m sure that anyone who has worked closely with users, produced educational videos, or listened to some of the frustrations the other users have understand why this terminology is confusing.

In keeping with the previous terms, we should be using terms like the following:

  • The WordPress Admin is the Dashboard, unless you’re talking about the actual admin user; otherwise, the user may not know what you’re talking about.
  • Taxonomies is a word for classification or categories. Depending on how you’re walking users through a project, it’s okay to use another term such as a category or a tag (or whatever their relationship may be to a post or a post type).
  • TinyMCE is just the editor. Calling it anything other than that puts us on the track for having to go off on a tangent explaining the name, and possibly explaining why it’s named that way, how it relates to WordPress, as so on.

The bottom line is that, to users, it’s all WordPress. Overloading terms (like the WordPress Admin when there is a Dashboard and an Admin User) can be confusing and doesn’t do a great job of explaining an idea to those who are reading, listening, or working with us.

Ultimately, our goal should be to make sure that we’re talking on their terms – we should not expect them to understand our terms, and we definitely shouldn’t use our terms to talk to others (and people do do this) for the sake of sounding more experienced, educated, and so on.

And I believe this if for no other reason than that the idea of simplifying a complex idea and making it easier for someone else to understand is the mark of a good educator.

Domain Language in Development

As I said at the beginning of this post, the idea of using a domain language is usually used more in conjunction with writing code in the problem space (or the problem domain), but shouldn’t be solely limited to that.

After all, everything that goes into providing a solution is related to the rest of the tools, applications, and things oriented around solving the actual problem. To that end, it’s important that we talk in their terms and not ours.

In a follow-up post, I’ll talk about the importance of using the domain language within the context of our code – from class names, function names, and variables – in order to show how the code should help mirror the terminology used in explaining and solving the problem.

But, for now, I urge all of us who are involved in writing, education, and helping others learn WordPress to refine our terminology to that it meets the user where they are (rather than expecting them to move on from there).


  1. Bob Dunn

    Couldn’t have said it better myself. And as a WP trainer for beginners and users, I hear the horror stories all too often. In fact so many come to me for my so-called “non-geek” approach.

    Interestingly, recently I had a client I was talking to. He was a smart, well-educated professional. An attorney, who actually and admitted he even has to be careful when talking to the layman. But one thing he shared with me was his frustration with the intro/demo videos of so many of the premium plugins out there. He said most he found were totally incomprehensible. Using terms and language that were beyond his scope.

    This post hits that perfectly. It’s not always easy for someone to step back into the shoes of the beginner, but if you can, you have made magic!

    • Tom

      In doing what you do, Bob, I’m sure you’ve had to deal with this possibly more than many others that I know who are involved with WordPress.

      Hearing your thoughts on this is significant, and knowing how you’ve worked around it is helpful, too :).

  2. Chris Howard

    Agree somewhat. I think sometimes people do have to learn the terms and language of a system. Ask a person from 20 years ago what a download is, or tell them to “download a file”.

    Dashboard can be confusing substitute for WP Admin, as there is a Dashboard in WP admin. Do you teach the user to “Go to the Dashboard in the dashboard”? Dashboard is a section of the WP admin. If I tell a user they need to go to their profile in the dashboard… they’re gunna get confused!

    I hate having to say “Taxonomies”, coz it does sound like a nerdy, sciencey word, but it is what it is and it is the term WP has chosen to run with. I’d actually like to see WP umbrella categories and tags under taxonomies to make it easier for the user to learn the term. Like they’ve had to learn other blogging, CMS, internet terms, it’s just another. If it get used uniformly and correctly, it won’t be too hard for the user to learn it.

    I think the problem is we introduced them to categories and tags first, so now we have to back track. It would be much easier to teach them at the top level about classification:

    Posts can be classified using what are called taxonomies. Taxonomies fall into two types, one that is restricted in what can be entered, and the other unrestricted.

    That is, those that are chosen from an existing pick list and broadly classify the content and usually in only one or two areas, e.g. a news site might have ones like: News, Sport, Fashion, Finance.

    And those that are free form text entered as keywords, that you may enter many. e.g. golf, Port Augusta, US Open, Tiger Woods.

    By default WordPress comes with one of each type: Categories for broad restricted classification; and Tags for the finer unrestricted classification.

    Developers can also add other taxonomies of both types to WordPress, which you will see in sites with specialist applications, such as eCommerce.

    (But I still don’t like the word “taxonomies”! )

    Regards, TinyMCE Editor, I’ve always just called it the editor, or sometimes the post/page editor.

    • Tom

      I think sometimes people do have to learn the terms and language of a system.

      Oh, definitely, but I think this occurs are a much more generalized level. That is, it’s true for things that are on a larger scale and/or for programs or behaviors that most people do.

      But on a smaller scale – such as which framework or tool was used to built whatever solution – I don’t think they’ll have to learn it as such.

      Sometimes, sure, but not as frequently as more widely used software.

      As far as the taxonomy / category / tag nomenclature is concerned, I think that if we can bridge the gap for others – that is, explain that taxonomies are a general label for how we classify things, and terms are the specific, say, label of a taxonomy then use category and category terms as an example, it may help.

      But even typing that sounds more complicated than it should.

      Regardless, it’s still one of those terms that I avoid using. Instead, I just talk about ways to categorize or classify information and it generally works well.

      • Chris Howard

        There’s a few WP terms I’d rather they’d chosen a little better. Taxonomy is one (I prefer the one you nearly used, Classification). “Custom post types” is another. It really should have been something like “Custom content types”. Posts itself is a term that I think is meaningless to many people, and I’d rather was Articles or Entries. Surprising since blogging evolved from journals, and you make journal entries. Post is more often the verb than the noun. You write an article or journal entry and post it online.

        I suppose debating terms is like the debate about icons, and whether they should be more generic, so less likely to display an out of date metaphor, like a floppy disk or dial phone handset.

        I do prefer terms that require less explanation, that are more immediately understood by a broader range of people, like Classification and Articles.

        • Bob Dunn

          Hey Chris, and I agree… and the most confusing:
          instead …. vs. a self-hosted WordPress site, and even then you will need to explain self-hosted… this is one that confuses tons of people :)

  3. Michael Musgrove

    This is especially good advice for those just getting into freelancing or a situation where they’re the salesperson as well as the builder of the user’s product. Freelancers spend a lot of time in different worlds each day, each with their own vernacular, and maintaining a different vocabulary for each audience may be more than many want to spend time on. Or for whatever reason.

    Something I remember when dealing with clients, and particularly prospects, is don’t sell the technology. The vast majority of people don’t care anything about WordPress, the code or framework you’re using, or anything that could be construed as geeky. They just want their problems solved as comfortably as possible. If I keep that in mind when talking to users from the beginning, it helps reduce the jargon and keep us on a level conversational ground. Miscommunications are minimized from less translation being necessary, on either person’s part.

    • Tom

      This is especially good advice for those just getting into freelancing or a situation where they’re the salesperson as well as the builder of the user’s product.

      This is a good point – it’s one of those things that’s easily over looked whenever writing about it, and I’d like to think it’s assumed when someone makes the moves into freelancing or self-employment, but it’s always a good idea to be really clear about.

      For every department that exists within an organization or corporation, you’re playing that role at some point :).

      They just want their problems solved as comfortably as possible.


  4. Dan Bernardic

    There’s also the concept of Ubiquitous Language:

    The problem you point out here seems to me to be very entrenched in the way we develop with WordPress.

    Contrast something like this in a functions.php file:
    add_action( 'customize_register', 'acme_theme_customizer' );

    The one means something we can all understand, the other is mostly wp-gibberish.

    • Tom

      The one means something we can all understand, the other is mostly wp-gibberish.

      This is true – ubiquitous language / domain language – all of it can contribute to making something much easier to read, follow, and understand, but there’s also the responsibility of striking a balance between that and the conventions of the framework or foundation with which we’re working.

      This isn’t to say that I’m 100% for the “wp-gibberish” or that I’m against it, either. I just think that it’s okay to expect developers to learn a little bit about the environment in which they’re working such that we can couple of coding standards and conventions with the approach of class names, function names, etc., that guys like Fowler, Martin, and Evans evangelize.

Leave a Reply

© 2020 Tom McFarlin

Theme by Anders NorenUp ↑