Author: Ipstenu (Mika Epstein)

Code By Any Other Name

While this post is mostly geared to how to better name WordPress themes and plugins, the concepts should be easy to extrapolate for just about any bit of code. One of the hardest things to do, as a developer, is to come up with a name for your plugin or theme. Sometimes it’s really easy, like if you want to make a plugin that shows the phases of the moon as a widget, you’d probably call it ‘Phases of the Moon Widget.’ But is that the best name to give your plugin?

One of the least obvious aspects of plugins is that the name you submit when you fill in the form on the WordPress Add a Plugin Page is the name you get for your plugin. So if you submitted ‘Phases of the Moon Widget’ then you get the url http://wordpress.org/plugins/phases-of-the-moon-widget, and that will also be the name of the folder on someone’s blog: /wp-content/plugins/phases-of-the-moon-widget/. That may not be what you wanted.

When you’re coming up with the name of your plugin, few people give thought to the ‘slug’ you get with your plugin. They try to think of a name that is evocative and descriptive, but often not short and succinct. One might think, in this Twitter/SMS world, we’d be better coming up with short plugin names, but we often get plugins like ‘recently-used-categories-with-alphabetical-or-most-used-ordering’ and then the author gets annoyed with his URL.

In fairness to everyone, this isn’t well understood. And even I have plugin names I regret in the long run. The process is a little mystical and magical to how someone should be submitting a plugin with name and description. After all, you have more than one name and description to consider. You have the name, the slug, the description and the readme. Ouch! How do you do it?

For this example, I’m going to pretend I wrote a plugin that pulls in data from mlb.com and sends an email to people on my blog every time the Cleveland Indians win a game. I plan for this plugin to be used for a BuddyPress community (The Base-Belles), but after I wrote it, I realized I could make this work for any MLB team, and for wins and losses. Thus I now have a plugin that, on my site, is probably called “Indians Game Winner Emails” and has a slug like “indians-winner-emails” or something weird like that. When I write code just for myself, I rarely concern myself with anything fussy with names.

I’ve also made a theme for this site that I want to share, and I’ve called it “Base-Belles” (after the site), but if I release this to the world, I’d want to make it something everyone can use for any team’s fan group, so I will genericize that up.

When you submit a plugin, you’re asked for a name, a description and a zip. So let’s get started. When you submit a theme, you’re uploading the zip directly, and it’s in there you pick your name and slug. So for themes, this is less of a hassle, but the basic principle remains.

The Name

Even themes have two ‘names.’ You have your slug-name and your name-name. As I go to submit my plugin name, I might be tempted to type in “MLB Game Results Emailer by the Base-Belles” and in some ways, that is a great name for a plugin. It’s descriptive after all. But the first thing you need to do is drop any mention of ‘by…’ with your submissions. That’s just not needed, as a theme has a style.css to show who wrote it, and a plugin has the readme. We’ll know.

That means your name is now “MLB Game Results Emailer” which looks great. Or does it. Do I really want the slug mlb-game-results-emailer? What about mlb-results-alerts instead? That’s not much shorter, but as a slug goes, it’s descriptive. Even mlb-results-mail would be better. They’re to the point, and when I read the list of plugins via SSH or SFTP, I’ll know right away which plugin it goes with. This means I will submit my plugin with the name “MLB Results Mail” and I’m happy.

If this was a theme, I’d call it “Base-Belles” after the site, and use the slug base-belles. Boy that would be easy. Except … I generalized it, didn’t I? Now I have “MLB Fansite Theme for BuddyPress” which is a good name, but a bad slug. So for a slug, I’d use mlb-fansite instead. My child theme for my own site will become base-belles and now I’m happy here too! If I was really clever and totally made the theme generic, it would become “Sports Team Fansite” and sports-fansite.

Descriptions

When we ask for a description what we really want is your short description. “This plugin sends an email to your subscribers every time your chosen baseball team wins a game.” Or a theme “This BuddyPress optimized theme is perfect for running fan-sites for baseball teams.” This is all anyone wants to see for a short description. It should fit in a tweet. Short, simple, perfect.

Why don’t we want all the details? Well for one you overwhelm us with too much information at once if you paste in the readme. And for another, themes and plugins gets hundreds of reviews to comb through a day. Keeping it simple and short saves us time, which makes it easier for us to work through high volume. Where we want to see details is in your readme.txt. These are absolutely required for a couple reasons. First (and most important) we want to know that you’re ready to go live. A plugin should only be submitted when it’s ready to be released to the wild, after all, and that means you have a fully finished wordpress.org repository page which is handled by (you guessed it) the readme. If I can’t read your readme and go “Aha, that’s how the plugin is installed and configured and that’s how I use it” then you have done something wrong. The readme.txt is your gateway drug. Love it. Make it sing.

Something I often tell people who have had plugins rejected is that when they resubmit “Put ‘I talked to Ipstenu about XYZ’ in the description so we know you’ve already spoken to one of us. That makes it painless for me to look in our group email box, find the previous conversation, make sure we’re all on the same page, and approve. Also if I both handled the earlier conversation and I see your submission, it’ll trigger my memory and I’ll get through your ticket faster.

ZIPs

As of today, you cannot submit a plugin or theme to the WordPress.org repositories without a zip. not a RAR, not a gzip, but a zip.

I love getting zip files, but many times people submit zips that don’t open on linux, or have another zip in them. What we want in that zip is your complete plugin that I could upload to a test site. A theme will be auto-rejected by their scanner if it doesn’t meet their standards, you’ll have to start over. Plugins we still review everything by hand, so we have to open your zip. Personally, I use TextWrangler, which actually lets me open a zip without having to unzip it, but sometimes people zip things weirdly and I have to open it and drag the folder up.

If you’re using Github, there’s a built in link to a zip, which you can send us. BUT. Keep in mind, the zip will not bring in submodules. Yeah, ain’t that a damn dirty trick? You can use it to update your own code, but anyone who pulls down a zip to test with won’t get it. That really annoys me, and I’m not sure if it’s a bug or something Git did intentionally. Oh, submodules. You’re so complicated.

Do we care what you name your plugin’s zip? No. Do we care that you’re calling that name explicitly in your code? Yes. Use functions to determine directories and save us all a hassle. Do we care about calling wp-config.php and other WordPress core files by name? We sure do, but that’s another topic altogether.

Summary

In summary? Short slugs, descriptive names, simple descriptions, detailed readmes.

Of course, that’s high level stuff and doesn’t explain how to pick a plugin name. I’m highly fond of puns (hence Genericon’d) or I name things based on their original concept (rss2email was plugin’d as post2email). Sometimes the name is just obvious (Rickroll). Do you have tricks for coming up with a good name?

7 August, 2013
DreamCon In Review

The weekend after WCSF I talked at DreamCon, which was our own little Webhost convention/camp for technology and other things. As Matt said, we’re kind of the wacky Webhost, and I love it that way here at DreamHost.

Some of my coworkers talked about the technical stuff, like WP-cli and how DreamPress works, but I talked about some slightly more esoteric and conceptual things, no coding involved topics, because I tried to think about the questions people who host with us asked me the most.

Choosing WordPress Plugins

This was the more geeky of the two, but was an overview on how I search for plugins, value the devs and their work, and determine which ones I use. I mentioned needs and wants a couple times, which makes me think I’ll end up giving people a talk on that one of these days…

The questions I got after this session were interesting. I preemptively answered the long standing question I had never been able to answer before, which is “What is your favorite plugin?” I finally have an answer, and it’s MP6. My eyes suck, and for me, MP6 finally made the back end of WordPress totally readable for me, without having to increase my browser’s font size. The font was better, and larger, and clearer. Normally I hate black backgrounds, but for some reason MP6 doesn’t give me headaches.

The best question I got was how to search effectively. My answer was to be more exact with search terms. Too often we go for broad terms and narrow down, but I like to go the other way. “wordpress plugin calendar event list” – I pick every major term I need in that plugin, and more precise results follow.

Get Out Of The Monkey House

Besides the fact that all the devs in the room cheered when I stated “code is art” I think this one really opened people’s eyes. Remembering that the design of your site doesn’t stop at the pretty stuff, that your content and the flow of how the site works is also a major impact, is huge.

By the way, code is totally art. You’re making something out of nothing, inventing and building a concept that never existed before. It’s just like writing music. Be proud of it. The most standout question from this talk was what do I do when a customer demands they stay in that monkey house? I put my foot down. When I get into contract work, I have always stated up front “You’re hiring me to be your expert, which means you may suggest things for your website that I, out of my experience and expertise, know to be bad ideas. When that happens, I will tell you that we should not do these things, and why. This is my power of veto. I will only use it when I have proof, via research, that what you are proposing is not in your best interests. If that’s not okay, then we don’t sign the contract. If it is, then you will accept my actions on web design, just as I will accept yours about your product. You know more than I do about that, I know more than you about this.”

Thus far, no ones walked away, and I’ve never made a website with a blink tag (except for the gag website, where the contract was to make it look like Ling’s cars…).

5 August, 2013
WCSF Video: Don’t Use WordPress Multisite

[wpvideo LYqducp0 width=”800″]

Too many people see Multisite as a silver bullet that can do everything they need, only to find out they’ve bitten off more than they can chew, and now they have a site that is too big, too complicated, and too much of a hassle. Understanding what Multisite does out of the box, what it’s best at, and where it’s easily extendable will help you build the right site.

1 August, 2013
How To Duplicate Content
I’ve talked about this before. 100% duplication of content on multiple sites is bad. So why am I going to tell you how to do it? And better, why am I going to tell you how to do it without Multisite? Because as a proof-of-concept, it was interesting.

The rest of this post tells you how to do something I don’t advocate, nor will I support. If you have a better way, or improvements, please leave comments. Otherwise, you’re on your own when you do this. I will not help you do it in any way, shape, or form.

Honestly, I still think this is a pretty silly idea. Duplicating content is a terrible user experience, and I still flat-out decline to accept any work for doing this. Sharing content is one thing, but 100% duplication of sites makes no sense at all to me. Yoast also says it’s a bad idea. But, if you really are totally 100% dedicated to do this, and you absolutely are going to, damn the torpedos, then you should do this in the least computationally expensive way possible. And that would be a single install.

Now all that said, this means you’ll need to do a lot of monkey-work, so why do I call this ‘easier’? In many ways, easy is relative and this will be hard, complicated, and may I stress, entirely unnecessary. You’re going the hard way around for something that good planning and a solid understanding of the Internet totally negates. Remember the absolute rule of the Internet: Use one URL per page and never change that URL. (With all rules, there are exceptions, of course.)

The way to make all this work, without Multisite, is by tricking your domain a little. There’s a neat trick with parking (or mirroring, depends on your host) domains, that lets you keep the other domain URL in your browser’s address bar. That’s what I do with this site, actually, halfelf.org is parked on top ipstenu.org. And with a park, the URL always stays as halfelf.org. Hey look! Two URLs, one site! Multisite has secret sauce to know “Someone’s coming to HalfElf, send ’em to site #2.” But on a single site, all my links would still be ipstenu.org and not halfelf.org.

Now how do you use this to duplicate content? You use relative URLs.

So here’s a real example. I have twofer.elftest.net set up to mirror plugins.elftest.net (which will give you a coming soon page, it’s just where I like to blow things up for tests).

In the beginning of this post, when I linked to my old post about Duplication Dilution, the URL was https://halfelf.org/2012/duplication-dillution/ and that is what we call an absolute URL. Because I’m mapping domains, I can leave those in without worry, but if I wasn’t, I’d change that URL to /2012/duplication-dillution/ instead. Right away this makes my URLs entirely relative, no domain name included, and I’m off to the races.

This doesn’t solve everything, though. See, WordPress really wants to use absolute URLs. There are plugins like root relative URLs, and those will help a lot. None of them back-ports your existing posts, though, so for that it’s nothing for it but to search/replace the DB and change your post content.(ONLY change your post content. Do not change GUIDs!) I really like those plugins because now for a new post, when I add a link and chose to link to existing content, it happily works:

And when I add an image, it too smartly handles as I want it to:

That’s the easy part of all this, though. Now you have to disable canonical URLs, so that you don’t end up with even more of the dread duplicate content penalty in WordPress.
```
remove_action('wp_head', 'rel_canonical');
```
This also stops WP from redirecting things like http://plugins.elftest.net/?p=1 as well, however, so keep that in mind. Of course, that’s what you wanted. But they don’t address the problem of your source code. If I view source on twofer.elftest.net, it still showed plugins.elftest.net, and that would be a problem for images and themes. You’ll need to toss in this to your wp-config.php, which will dynamically change your URL to be whatever URL I’m visiting from, so that changes automatically. Awesome.
```
define('WP_HOME', 'http://' . $_SERVER['HTTP_HOST']);
define('WP_SITEURL', 'http://' . $_SERVER['HTTP_HOST']);
define('DOMAIN_CURRENT_SITE', $_SERVER['HTTP_HOST']);
```
Now I want to tell WordPress that wp-content is not in URL/wp-content/ so let’s just put this in and make it relative too!
```
define('WP_CONTENT_URL', '/wp-content');
```
I’m still going to have to search and replace my old post content (I used Velvet Blues for this):

But that didn’t address the problem of the source code. 90% of WP now thinks it’s all on twofer, which is what I wanted, but look at XMLRPC:

And even better, when I try to log in via twofer, it still says I’m going to plugins. Oh and it doesn’t pass through cookies, so really, I never log in to Twofer. Realistically? This isn’t a problem. I’m always going to use plugins.elftest for all this when I log in on the backend, and since the convenience of all this was meant for the front end, and it’s just pingbacks. And why is that? Honestly, I don’t know. I have a guess that since, at WordPress’ heart, the site is always plugins, the absolute URL there has to be what it is, but in so far as all that goes, I think it meets the needs of why most people want to do this.

Conclusions? You can do this. If you wanted to, you can hardcode the theme so the domain you visit the site with will dynamically change the header image, or widgets, or anything else you want. PHP is pretty cool that way and WordPress is too. But I would never do it, except as an experiment to see what I could do it at all.
31 July, 2013
What WordCamp SF Means to Me

Andrea Middleton asked me to write something about either my upcoming talk today at WCSF or about the camp in general. I thought about it for a minute and sent her this:

I probably have one of the stranger (but not strangest) associations with WordCamp San Francisco: abject terror and absolute salvation.

In 2012, I went to WCSF for the first time, amidst some of the roughest professional turmoil of my life. At the time, I worked for a bank and was exceptionally unhappy with my work. I really wanted to work doing WordPress, and had spent much of the last 12 months applying to places and just not finding the right fit. Then I decided I should go to WCSF and see if I could make magic happen there, so I bought a ticket and had my car decide that brakes were optional. Short on the money for the trip, I appealed to the community, crowd raised the funds, and the day after I made goal, was asked to speak! I’d never spoken at any WordCamp, but I said yes because I was determined to change my life. Serendipity happened again, and I was contacted by DreamHost about a job. They too were coming to WCSF, so we had an interview and then agreed to meet up after my talk. This meant my talk was also part of my interview, and thus extra terror set in.

Of course, everything worked out perfectly. Now I’m happily employed doing WordPress work, traveling the US talking at WordCamps, and otherwise helping the community at large, being paid to do what I love.

Source: WordCamp SF 2013

Later today I’ll be talking about why you shouldn’t use WordPress Multisite. Spoiler alert: I love WordPress Multisite.

26 July, 2013
My Question is “You Suck”

If you’ve ever watched Survivor, they have a Tribal Council at the end of each episode, where they discuss things and decide who to vote off the island. In the grand finale, however, they instead discuss whom to give the million dollars. Every previously voted off tribe member gets a chance to ask the two (or three) finalists a question. Miss Alli, from the classic days of Television Without Pity, used to love/hate when someone would step up and use their time to shout, insult, or otherwise berate the finalists. She called that “My Question is you suck.”

Whenever you do support, you will invariably run into people who act exactly like that. If I had a dollar for every time someone left a support ticket with “This sucks!” I wouldn’t need to work anymore. And those people are really annoying, because you want to reply “Well thanks, and over here in the constructive world…” but you absolutely cannot engage them. As the Survivor yahoos quickly learned, feeding the fuel for someone who’s ranting is about as useful as keeping the rain off with those little paper umbrellas you get with fruity drinks.

My question is … this code is crap

Something to keep in mind, Tech Support is not “Customer Service” per se. When someone needs tech support, while they totally need someone to be ‘nice’ to them, they really need someone to fix their problem. Customer Service is all about building a relationship with the customer, figuring out their needs and wants, and basically selling them something. On the other hand, tech support is being told “This is my problem, fix it.” While that certainly happens to people who work at hotel desks (“There’s no hot water…”) it’s the meat and milk of life for anyone who writes and/or maintains software.

To this end, you’re really not ‘servicing’ the customer, nor are you taking time to build a great rapport with them, you’re trying to fix what’s wrong. Certainly doing this provides a service to the customer, but making sure the person comes back (or stays) is often secondary. After all, if we can fix the problem, you’ll come back, right?

When someone just says ‘You suck’ or ‘Your code sucks’ there’s very little you can do about it, if they’re not willing to give you a concrete example of these things. I have, on occasion, replied “Patches welcome! I’m always happy to improve my work.” That’s pretty much the best I can do. When the reply is that I, personally, suck, then I hand it over to anyone else. There’s nothing I can do here, so it’s time to ask someone else to help me out.(If you’re the solo dev, it’s time to cut your losses, say that you’re sorry you can’t help them, and walk away.)

My question is …. this plugin gets one star because it doesn’t work

Mark Jaquith Reviews Code. Credit Mark Jaquith

Everyone hates the ‘review that should have been a support question.’ Invariably we’ll get it. The plugin doesn’t work, screw you. And when we go back to look at the person’s post history, we see never once did they, in a place you can find, ask you ‘How do I make this work?’ It’s frustrating. Now you should keep in mind, on the WordPress.org forums, someone can change their star rating, so the best thing to do here is try and win them back. Kill ’em with a little kindness, point out ‘I would have seen this faster had you…’

But in general, this one is not to terrible to win back. Much of the time, someone who is this lost that they can only find the review location and not the right support places is someone who has a pretty easy to fix issue. Solve it and you’ve got a returning user. A smaller percentage of the time, alas, the problem is someone who really, truly, didn’t read what the plugin does. “This plugin for vegan resources sucks because there’s no bacon!” Not much you can do there except point out “This is by design.”

My question is …. you don’t reply fast enough for me

Today we expect, and often get, instant feedback. We have livechats, we have Twitter and Facebook. We reach out to the people who represent a company (or a TV Show), and we assume there will be some prompt reaction. This is no longer customer ‘service’ but ‘experience.’ The customer’s personal experience will color their feelings about both the product and the people behind it. It’s a large part of why I don’t think pure customer service exists any more, if it ever did, in software.

The problem comes in when you take a weekend off, or an afternoon, because you want to actually have, you know, some time with your family, or go to a movie. Maybe you were just asleep for eight consecutive hours. Either way, it was the worst time in the world for someone else, and they’ve left multiple requests for help. If you’ve ever worked in a ‘traditional’ office, these people are like the guy who emails you a long question, and then calls you and swings by your desk, after IMing you, to make sure you got the email.

In short, they hit every single ‘annoyance’ nerve in a person’s body, all at once, and they do it over and over and over. I tend to want to reach through the monitor and take away their caffeine for a couple days. But until someone invents that for me, I have a couple tactics.

For anything ‘free’ (like WordPress plugins) I tell them that this is a free product I write in my free time, and that means waiting a reasonable time for a reply means waiting 3-5 days, not 3-5 seconds. And then I answer their question as best I can. For the paid stuff, I point out that I missed their email because I had gone home for the day (or ‘had the weekend off’). Usually just that gentle reminder of “some people do work ‘normal’ hours still” gets them off their horse enough to work with. On the rare occasion it doesn’t(I’ve had people tell me that I’m too important to not be available 24/7, which is sweet, but no.) I’ve just ignored their unreasonable demands and concentrated on fixing the problem at hand.

My question is … you don’t know what you’re talking about

Finally there’s the you suck hidden in a peculiar phrasing of basically “you aren’t good enough.” This is not the same as the outright “You suck.” because it’s actually a value judgement. It’s not a dismissive “You’re a meanie poopy head!” sort of claim, it’s a “Your code sucks!” And this sort of comment hurts a lot. People calling you names rarely have any basis to do so, and they’re rarely right. People calling into question your work, however, that cuts to the bone and tends to make us over react.

In defense of people who submit bug reports, much of the time this is not what they mean! Sometimes they say “I think you’re wrong because of XYZ” and it comes across as “You idiot, how could you not possibly know this!” I say this a lot, but text is a really lousy medium for communication of intent. Now. One thing the people who report the bugs really need to remember to do is say “Thank you” when the bug is fixed, or even “I appreciate you taking the time to explain to me why you won’t do XYZ.” Instead, most of what we get is someone saying “I told you! I was right and you were wrong!” I gotta tell you, that never really makes me want to work with you again.

But the real reason this one galls me is that it’s generally said to me after someone has specifically asked me for help on something of I’m somewhat of an expert (or talented tweaker). I’ve had people tell me I don’t know jack about WordPress (pretty sure that’s wrong), or pretty much anything else under the sun. That frustrates me, since you came over here asking me, admitedly a total stranger, for help, and when I gave it you snipped that I’m ignorant.

To these, I actually do point out “You know, you asked me for my help/opinion and I gave it. We can agree to disagree, but you don’t have to be mean about it, since that’s not a good way to get help from a free, volunteer, community.”

Unless of course you’ve hired me, at which point I refund most of your money and cancel the contract.

22 July, 2013