Home » 40 years online » How my custom URL shortener taught me the 10 principles of tech support

How my custom URL shortener taught me the 10 principles of tech support

by Alex in | | | | | | |

The Internet in 1975.

January: A map of ARPANET now shows 61 nodes.
Date unknown: David W. Packard builds the first Ibycus, a computer for classicists.
November: Bill Gates first uses the name "Micro-soft" to refer to the company he has just created with Paul Allen.

The most important computer in my childhood home was invented in 1975, though we didn’t get one until the mid-1980s. To say “we” got one is misleading, though, because the Ibycus was my mom’s computer, plain and simple.

The version my mom got was a lot more compact than that first, 1975 effort, but the underlying vision was the same: put the entire corpus of ancient Greek texts into digital form, and give classicists the tools to use them. For my mother, a papyrologist, it was revolutionary. Suddenly she had access to volumes of Greek literature in CD-ROM form.

I can barely remember what her Ibycus looked like, but I do remember the tech support. The Ibycus was the pet project of David Packard (yes, that Packard) a classicist who put his family’s tech resources in service of classical research and teaching. It was hardly a mass production kind of machine, and so Packard personally provided the tech support to classics profs who ran into trouble. Even as a teen I knew enough to be stunned by the fact that my mom’s SOS calls rang through to the guy whose name was on our printer.
In all my years of computer-buying, I’ve never had a machine where tech support was provided by the guy who designed and built it. Nonetheless, I’ve had plenty of great experiences…and plenty of terrible ones. For a long time I set the bar at: gets to my call within 20 minutes of placing me on hold, and doesn’t talk down to me (too much) because I’m a girl. (These days, Shaw Cable gets my highest marks in this regard, because their tech guys not only answer the phone, but are perfectly willing to help me get access to the IEEE port in the back of my cable box.) Most recently, I’ve evaluated tech support in terms of the speed and calibre of Twitter replies: if I bitch @aboutyou, I want to hear from you.

A map of ARPANET in 1975 shows 61 nodes

From computerhistory.org

As you might infer from the above, I’m not easy to make happy, support-wise. Tell me too little and you’re unhelpful. Tell me too much and you’re condescending.

That’s why I was thrilled by an e-mail I got ten days ago. I had sent an SOS to SonicCat, the tech consultants who have our backs on everything from Drupal dev to server setup. One of SonicCat’s partners is Natasha Scott, who was our project manager at Social Signal, and is a wireframing, drupalling rockstar. The other half of SonicCat is Mike Kelly, who we count on for everything from system administration to advice on radiation exposure.

Since Mike is the guy who set up our web server, he’s the guy I turned to for help when I hit a wall in setting up YOURLS. YOURLS is a set of PHP scripts that let you host your own URL shortener, so that instead of linking to http://bit.ly/hNgxWi I can now link to http://alexlov.es/one40yrold. Hot!!

But while installing YOURLS on our server, I ran into trouble, and asked Mike for help (if you’re not interesting in YOURLS you may want to skip over the details of our correspondence):

I have to admit to [semi] defeat because:
(a) I can’t really figure out how to setup a new domain on our Linode account (my newly created alexlov.es master zone just points to alexandrasamuel.com)
(b) I logged in as root and created alexlov.es as a directory in the same directory as alexandrasamuel.com, but from my poking around i infer there is something we need to do to enable hosting of multiple domains on a single server
(c) I can’t figure out where i’d upload my Yourls files to (not www, presumably…but not htdocs either once I have it inside alexlov.es? I’m baffled)
(d) I’m not sure what my table prefix should be for my database (as per http://yourls.org/#Install — configuration tab)
OK, that feels like the entirety of my bafflement for now. I guess this is officially non-urgent bc i’m going to Romania tomorrow and probably won’t fuck aroudn with this while I’m there. At least, I really hope I can resist.
So…thanks in advance for whatever help you can provide. i’m really eager to setup Yourls myself but I do seem to be a bit stumped in terms of next steps on Linode.
And here’s what I got back from Mike, less than 12 hours later:
Hi Alex,
Unfortunately, I don’t seem to have the root password to that system, just Rob’s password … so I can’t actually make these changes for you at the moment. But you were on the right track & identified the problem:
When you have multiple domains being served up by a web server, you need to tell the web server process about it. The web server needs to be able to map each domain name to a separate directory of files.
In the case of alexandrasamuel.com, we’re running the nginx webserver.
/PATH/nginx/PATH/ is a folder that contains a repository of web server configurations for sites you may potentially serve up.
If you look in /PATH/nginx/PATH, there is a “default” and an “alexandrasamuel.com” file. You’d want to copy “alexandrasamuel.com” to a new file, ie: alexlov.es – and then edit that new file & replace all instances of the old domain with your new one – and make sure that the document root & log file directories exist (ie: /PATH/PATH/alexlov.es/htdocs and /PATH/PATH/alexlov.es/logs). You’ll also want to make sure that the ownerships are correct – the www-data user needs to be able to write to the logs directory.
Once that’s done, you need to tell nginx that it really does need to serve up that domain. That’s done by creating a symbolic link (aka an alias) to your newly created alexlov.es config file. Nginx looks for this info in /PATH/nginx/PATH/
So, you’d do something like this:
ln -s /PATH/nginx/PATH/alexlov.es /PATH/nginx/PATH/alexlov.es
and once that’s done, you restart the web server:
/PATH/PATH/nginx restart
Note that these steps would be the same if you were running Apache as opposed to nginx – just some of the directory locations would change (/PATH/apache2 instead of /PATH/nginx). If you want to switch back to Apache we could probably do that as well. You may want to think about doing that. Yourls is designed to work with Apache, although it can work with nginx as well, according to this:
I just realized something though – the /PATH/nginx/PATH/alexandrasamuel.com file is set up to serve WordPress documents – copying it & using it to run Yourls may or may not work well. Your new alexlov.es config file might need to be tweaked a bit (see link above).
Finally, re: the Yourls configuration:
From what I can see, the Yourls files would be uploaded to /PATH/PATH/alexlov.es/PATH/ -> that’s the document root directory that your web server would serve content from.
As for the database table prefix, you can make it anything you want. Why? The thought behind having configurable table prefixes is so that you don’t experience conflicts if you run multiple applications out of a single MySQL database. Some hosting providers only give their customers 1 database. If you had two web applications (say WordPress and Drupal) and wanted to run them out of the same database, you’d run into trouble as both have a table named “users”. But if you give the tables a unique prefix, like wp_ and drupal_, then your wp_users and drupal_users tables would never conflict.
In your case however, you run our own virtual server. You can give yourself a separate database for every application. So it doesn’t really matter what you set the table prefix to. Go ahead and use yourls_ if you’d like.
Hope that brain dump helps. If you want me to give you a hand with the actual config/setup, let me know.

UPDATE: I edited this email to replace some key information (wherever you see “PATH”) because Mike points out there is no reason to give people (i.e. hackers) a roadmap to my server setup. Another great example of pro-active tech support done right.

Mike’s e-mail has set a new high watermark for tech support as far as I’m concerned. If you want the tech support you provide to be as helpful as Mike’s, here’s the path to follow:
  1. Calibrate your advice to the skill level of the recipient. If you’re helping someone who doesn’t know the scripting language or operating system you are working in, give them the specific code or command to type.
  2. Don’t waste your time transcribing instructions you find online: just provide the URL and say what information is relevant.
  3. Read the complete list of questions and answer all of them.
  4. Respond in a timely way.
  5. Don’t fix a problem yourself unless you’ve been specifically asked to: answer the questions that will allow the recipient to fix it.
And here’s what you can take from my e-mail, if you’re asking for tech support yourself:
  1. Ask for help from the person with the best context to provide an answer — i.e. the person (or company) that built the software, configured the computer, set up the server.
  2. Be as specific about your problem as possible, breaking it into pieces or steps if necessary.
  3. Google for relevant resources, and share anything you think might be helpful or relevant with the person you’re asking for help.
  4. Be clear about what kind of help you want: do you want your problem fixed for you, or do you want help fixing it yourself?
  5. Share your timelines so that your tech support person knows how quickly you need a response — and don’t ask for a quick response if you don’t actually need one.

Good tech support is the grease that keeps the wheels of the Internet running smoothly. If you know where to get help, or better yet, know how to help yourself, your tech experiences are likely to be positive and satisfying. If you don’t know how to troubleshoot, or feel belittled when you ask for help, you’re going to have a hard time enjoying or using computers and the Internet. And when you are able to offer help as well as receive it, you discover the appreciation and generosity that represent the very best of Internet culture.

At its best, tech support can catalyze those aha! moments in which technology mastery becomes a catalyst for increasing your confidence and your sense of agency in the world. At its worst, tech support can leave you as baffled as if you were reading Greek without an Ibycus.

First posted on March 30,2011
  • http://twitter.com/ddougan Des Dougan

    Great article, Alex. Fits pretty much with my MO (I have a support business focused on the small business sector). Mike’s response to you was really clear, too. Enjoying your 40 days of articles.

    Des

  • http://twitter.com/ddougan Des Dougan

    Great article, Alex. Fits pretty much with my MO (I have a support business focused on the small business sector). Mike’s response to you was really clear, too. Enjoying your 40 days of articles.

    Des

Previous post:

Next post: