A Vietnamese Tour Guide’s Freelancing Tips

Over Easter I had the opportunity to visit northern Vietnam for 5 days. On my last day there, I met Tung, a freelance tour guide. To find work, Tung spends time in an open park by a high end hotel where he meets tourists and engages them using a well-practised (and effective!) pitch.

If you are a freelancer or consultant, you know that finding clients is a key factor in the success of your business. There are three parts of Tung’s process that you can apply to your own strategy for finding clients; he was in the right place, he started by building rapport, and he established credibility before making his pitch. Tung’s approach was much more effective than those of the typical vendors I encountered.

The Typical Vendor

For most vendors, selling their products or services is a numbers game. They price low and hope that you are in the mood to buy when you happen to encounter them. These vendors know that there will be crowds of tourists passing them every day; they can make enough money to survive by selling to even a small percentage of this traffic.

If you’ve tried finding work on oDesk or a similar job posting, you’re using this technique. When you list yourself on sites like oDesk, you’re just another vendor, offering the same product as competitors. You aren’t able to differentiate on the service that you offer, so you have to differentiate based on price, leaving you to fight it out in a race to the bottom.

What I Learned From Tung’s Approach

Tung did things differently, he knew who his ideal customer was and had staked out the best spot to find them.

1. Position yourself where clients will find you

Tung was in an open, public area, near a high end hotel, away from the chaotic bustle of a typical street. By intentionally placing himself there, Tung knew that he was directly in the path of foot traffic from visitors with money to spend and that the open, low traffic nature of the park meant that he would be seen and acknowledged when he said hello.

As a freelancer, you need to put yourself in the path of potential clients, in a venue where they will stop to acknowledge who you are and pay attention to what you have to say.

Find out where your ideal clients are and spend time there.

Being around the type of people that you want to work with will allow you to learn what they are looking for and how to talk to them about it; this may be a physical location, or an online community.

Stay away from the crowds

To stand out, you need to step outside of the crowds of people hawking the same wares you’re trying to sell. Imagine heading down a street filled with 30 fruit vendors. How are you going to pick? At best, you’ll buy from one person; however, too many choices leads to indecision and the majority of people will probably not buy there. This is analysis paralysis, anxiety brought about by abundant choice. If making decisions creates anxiety, it will be easier for the consumer not to make any decision if they are forced to choose between too many.

In Tung’s case, he was in an open, empty space of a park, so when he said hello, he got our attention. We didn’t have to decide between him and somebody else and as a result, we listened to what he had to say.

You need to get away from oDesk profiles and job board postings where you’re just another faceless vendor in the crowd. In our industry, listing yourself like this creates analysis paralysis for the client; the only way you can differentiate yourself from other freelancers is by being the cheapest possible option. The buyer will become overwhelmed and either choose the lowest cost solution, or make their decision elsewhere. Being a low cost solution may seem like a successful way to find clients, but for you, this approach inherently can only lead to more work for you, for less money.

Instead, find out where your ideal clients like to spend time, either online or in real life, and then spend time hanging out there. If you’re in the right place, you’ll be able to get the full attention of these people and won’t be fighting as much competition.

2. Build Rapport

After Tung said hello and asked where we were from and what we did, he asked a few questions about our country. He may have only known four facts about Canada, but he used them to start a conversation with us without triggering our “keep moving, this guy just wants to sell us something we don’t need” sense.

Typically, vendors lead with the sales pitch – “Please?” they ask as they motion towards whatever it is that they’re selling. We say “no thank you,” and move on.

Imagine if everyone you met, everyone that had even the remotest chance of giving you work you said “Please?” to and waved your portfolio frantically in their face? Instead, what if you were to ask them how they’re doing and ask a few industry specific questions about their business?

The first example is the same as saying “I’m a [developer/designer/copywriter/etc], do you want to hire me?” It shuts down conversation. There are only two answers to the question: yes and no. In this type of situation, it’ll usually be no.

In the second example, you’re building a relationship. You’re not someone desperate for work from their perspective. You’re interested in getting to know about them, who they are, what their problems are. Relationships are a vital factor in the success of your business. Building a relationship leads to a long-term investment — maybe the potential client doesn’t need you right now, but guess who they’ll call if they need some help in the future? Not any one of the five, scared looking developers who wouldn’t let them enjoy the cheese platter at the conference lobby in peace. They’ll call you.

By asking about us first, Tung made us feel like he was more interested in our interests than his own. He put a higher priority on us as humans, rather than cash dispensing tourists. Instead of just saying, “No thank-you” and moving on, we stopped and chatted with Tung, simply because he put us and our interests before his own.

3. Establish Trust

Once we’d exchanged a few bits of conversation, Tung let us know that he was a tour guide, but instead of outright asking us if we wanted him to take us around, he said, “Look at my book.”

Inside the book were emails from people he had guided around the country, all sounding very positive. He showed us pictures of himself with other people who looked like us and photos of him with his family. “This is my wife,” he said proudly, pointing at her.

In an unknown country, picking the right tour guide or set of activities means the difference between a great trip, (seeing beautiful areas and experiencing the culture) and a miserable/boring trip, (getting ripped off, or herded around with all-inclusive tours).

As a freelancer, my clients are similar to myself in Vietnam on vacation; they are adrift in an unfamiliar culture and language. They don’t know the details about how to build an effective piece of software, or a website that can sell their product. If they pick the wrong tour guide, they end up getting ripped off with a solution that doesn’t meet their needs, or a boring, mass-market implementation.

We can establish trust with our potential clients by showing them our past work and testimonials from satisfied clients. Without these elements, a client would be taking a gamble on our capabilities, similar to picking a tour guide at random in Vietnam. You don’t know if you’re going to end up with something great, or if you’ll get a crappy deal.

Timing is Everything

After looking at a few pictures and reading his emails, we said goodbye to Tung. Our flight was leaving in a few hours and we just wanted one last coffee with condensed milk in traditional Vietnamese style.

In the end, the timing wasn’t right. We didn’t need a tour guide for the day, but the experience was memorable because it was so different from what I’ve become used to while travelling. Also, if I’m back in Hanoi, can you guess who I’m going to contact if I need a tour guide or want advice on travelling?

When you’re meeting potential clients, you’ll have a similar experience. Most people won’t need you right then and there, but when they do, you’ll be ready for their call.

Lessons Learned: Successes and Failures of 2013

Career wise, 2013 has been the best year of my life; both financially and with my own personal fulfillment from work commitments. Just as importantly, I’ve been learning what motivates me and am transitioning my business to focus on these factors, rather than just focusing on the financials. Here’s a quick list of accomplishments:

  • Increased my take home income by slightly more than 60%
  • Won the biggest contract I’ve worked on yet
  • Wrote 1/2 of a book about Ember.js (to be completed this year)
  • Visited Portland twice, San Francisco, Philadelphia and spent two weeks at a remote cabin on a lake with no electricity or phone reception
  • Moved across the Pacific Ocean to Hong Kong from Victoria, BC
  • Built my blog from nothing to 34,000 views
  • Got 117 subscribers on my mailing list

What did I do right?

These are three huge lessons I’ve started putting into practise that are helping sleep better and allowing me to move confidently into the new year.

Systematize Everything

Over the past year I’ve systematized and automated as much of my business as possible. I’m just one guy and though I hires sub-contractors at times, it’s basically just me. My bookkeeping and time tracking needs aren’t that complex, but automating it allows me to have instant focus on the health of my business. Having this kind of real time statistics about the health of my business allows me to make better decisions and plan for the future, rather than reactively working whenever the work comes in. I don’t have to be in survival mode, constantly wondering if I’ll be able to pay next month’s rent or if I can pay my sub-contractors. This is a huge relief.

Write more. Seriously.

In May I was at a conference where Nathan Barry gave this talk. The lesson I took home is that at a certain skill level in my field, the difference between me and another guy will basically be what people know about me. I can tip the scales massively in my favour just by having an established audience in my areas of interest and expertise. At this point, I haven’t made a single dollar from writing, but I have noticed a huge improvement in my ability to convey my thoughts in writing. Also, I think at least 50% of the people who have visited my site (maybe naively) got the information they were looking for. At 17,000 people helped, that’s not bad.

As a secondary point, writing more has also given my communication skills a huge boost. Since I’m almost certainly going to be working with people for the rest of my life, I’m glad to be developing this skill. The result is that I’m more enjoyable to work with on the positive side of things, and when things are heading in the wrong direction I can steer them back in the right direction in a more positive and constructive way.

Charge More.

This is universally good advice. It’s something that I tell anyone who is struggling as a freelancer. I’ve found that there are two parts to this – the first is just simply to charge more. Based on my experience, most of the time the difference between what I’ve charged and a 50% increase is just saying the number that’s 50% higher. The second part is to focus on communicating the value that you’re providing (see the previous point about getting better at communicating) and your clients will love the work you do for them. When ever I’ve worked hard and done good work but not talked to the client explicitly how what I’ve done will benefit them, it’s gone poorly. Spending the extra time to tell them how my work is going to affect them positively has never been a bad decision, in fact, it helped to save a project that went over budget by illustrating how the extra costs to them actually provided positive value over the long run.

What went wrong?

Part of what’s made this year such a success for me is the fact that I’ve been able to have a clear vision about what hasn’t gone right. In the past, things wouldn’t meet my expectations, but I couldn’t explain clearly why they hadn’t. This year, I can tell you exactly what went wrong, and why. That being said, there are only two things that I would say are actual failures.

Didn’t deliver on my Ember.js book

I’m writing a book about Ember.js. I’ve been building JavaScript web apps for a few years, and by far, Ember is the best one I’ve worked with. That being said, getting accustomed to “the Ember.js way” is definitely not so easy, but it’s worth it for the productivity and code quality gains that just come with it inherently. I digress.

I didn’t finish the book. It’s about halfway done and I feel like I let myself down with this. Instead of making time for book writing, I was distracted and unfocused. I spent a lot of time doing other cool stuff, but that stuff doesn’t contribute to me building and launching my first product.

Didn’t email my list

If you’re on my list, sorry! I love you guys, but also, the idea of sending a message to you scares me. Part of the reason that I haven’t emailed is that I haven’t felt like I’ve had anything good enough to say, but I do. You’re interested in learning about Ember.js and I’m interested in teaching you how. Anyway, you can expect something coming very soon, but for now, I don’t have anything. In a week or two you’ll get my first email about the book and then we can start going from there. If you’re not on my list – sign up at www.learnemberjs.net

What I’ve learned

This is the most valuable part of this post for me. Looking back retrospectively, I’ve identified that the major things standing in the way of meeting my goals are basically strengths gone awry. If there’s one thing that I can take from 2013, it’s the idea of focus. Without it, I’m lost. Every new idea or opportunity that comes my way feels like the first chance to go to Disneyland as a kid. 2013 was a lack of focus, I was like a puppy with new opportunities to chew on everywhere. 2014 has the same opportunities, but I know which ones I’m going to sink my teeth into. During 2013 I read books and articles, attended workshops, went to conferences, and thought a lot how I wanted a product based income. I failed to make even a single dollar, because I didn’t put enough effort into one thing instead, I divided my efforts out into a lot of things. That’s my lesson. If you want success, define what that means to you and then work backwards setting goals that will bring you there.

Lack of Focus (I Need an Iron Focus and Determination)

Last January I decided that I wanted to develop a product for an additional source of income. I came up with the idea for a book on Cordova (PhoneGap), but in the end, it wasn’t a tool that I wanted to spend a lot of time with and really dive into. Instead, I’ve spent a fair amount of time writing a book about building web applications with Ember.js, and I have to say, it’s good (but I’m a bit biased..)

Why didn’t it ship? Basically, I didn’t ship this book because of a lack of focus. Instead of focusing on the things I know would move the needle, I’ve wasted time on all kinds of yak shaving around optimization and stuff that is totally unnecessary. Instead of writing or focusing on learning and practising, I’ve spent time consuming information around the periphery. Yes, there’s a time for learning, but more often, it’s a time for action. To change this inaction, this year I’m focusing on three month planning period for macro level goals, which are laid out by defining SMART goals for each week. Those are Specific, Measurable, Action-Oriented, Realistic and Time Bound.

I thrive on variety and love to have a number of things on the go, but this works against me when I don’t have a stringent focus on accomplishing the things I want over the long term. My career is a long game play and I’m in it to win. I believe this will be the number one thing that will help to get me set up for success this year.

For example, You can expect a followup to this post in early April where I’ll write about my 2 products and how this new focus has gone.

Project Management Software is Broken

Go to /r/freelance on any day of the week and invariably, there will be a post asking which project management or time tracking software to use. The answers are always the same. There are two types of results:

  • big names like Basecamp, Asana, Trello, Harvest, and Freshbooks
  • the little guys, which may or may not be the next big thing.

People have been building online project management software for over 10 years now and we’re still seeing the same iterations on a theme. The laundry list of basic features never deviates – grab 5 or 6, a good designer and developer and a few months later, you’ll have built a project management app. Just combine to-do lists, file uploads, and calendars with the people that are working together. Some accomplish this with a side to side layout and calling the to-do lists stories, some use a sheet layout with plain to-dos.

If you’ve worked on the internet, you’ve used this stuff and you probably know what I’m talking about. If Basecamp is working for you, that’s great and I’m not writing for you right now.

Here’s the underlying issue:

Project management software assumes that you care about it

And not just you, but your client, and your employee, and that sub-contractor, and your designer. You get the picture. And, by the way, the project management software is probably wrong.

From behind the scenes, the software company that’s making whatever solution you’re using spends a lot of time trying to get you to care. They think about it a lot and they’ve probably designed a great onboarding process that gets you to add things to the list and invite your team members. Getting you to care is their job. It reduces the chances that you’ll stop using their product and then some day cancel your account. It increases your lifetime value, and reduces their churn rate.

But we just don’t care. I’ve been invited to Basecamp almost 10 times, Asana a handful, and Pivotal Tracker. Each time, I have to learn some new way of flowing through a project.

I get that this is necessary; I manage projects. I need a tool to keep things organized and help me keep track of where things are at. If I don’t use something, I fail. I’ve failed really badly with a few projects because I didn’t use project management software, so I understand the WHY behind this stuff.

So, we’ve established that currently, project management software is probably most useful to the project manager. For everyone else, it’s usefulness lies somewhere lower down along a graph that displays “REALLY USEFUL, CAN’T WAIT TO LOG IN” to “stop wasting my time, stupid website.”

Statistical analysis of caring about project management software to role.

Statistical analysis of caring about project management software to role.

Most people don’t care about the project management software

The underlying assumption that all of these tools are built on is that there are two types of people: people who really want to get stuff done, and people who really want those other folks to keep getting stuff done.

Obviously your client wants you to get stuff done. That’s why they hired you, and that’s why you added all of those things into the website so that someone else could check them off.

Your designer and developer probably don’t care that much about getting the same stuff done that you or your client care about. They’ve got other needs; they want to refactor that user model the last guy wrote because it kind of smells. They’ll do the things on the list, but only because at the end of the day/week/whatever review period, they know they’re going to have to give you a reasonable answer as to what it is that they have been doing for the money that you’re paying them.

Your client doesn’t care about your project management software. If they do, well, that’s weird because it’s not what they’re paying you for; in fact, their caring will likely cause you more problems. But basically, they just want to get some kind of progress report and be kept in the loop whenever you’re making an important decision – like whether or not their logo should be the same ‘cool’ colour green that Nike running shoes seem to be all about these days, or if you just want to write ‘buttz’ in 72px font on their home page.

Project management software should care about you and everyone else too

So, I’ve established that project management software isn’t doing a great job, but I think it could. Here’s what I would love to see.

Send me really nice emails

I want the status reports to feel like a warm hug, because things are getting done. The software should be able to send really nice looking progress reports to the project manager and the client. If anyone else cares, they should be able to opt in.

I’m assuming that this is something that’s probably happening more often these days, but I remember getting a lot of janky, almost plain text emails with a bunch of individual to-do list items marked off. This doesn’t help me see the overarching picture, or how we’re progressing.

Don’t make me leave my inbox!

If we’re sending an email to someone, don’t make them leave the inbox and then send them to a login screen. If the email requires a response, you should be able to reply directly or just click a link in the email to submit a response.

Just stop making me log in.

When the client, a worker, or I get an email that doesn’t require a response, there should be a link that lets you view the project right from there! Like a forgotten password link. It’s not hard. For security, if they want to edit or change something, THEN ask for the password. Most people are not super tech stars and don’t have 1Password or LastPass installed. Just remove this barrier.

Remind me if I’m supposed to do something and I haven’t done it

But please do it nicely. A simple – “Hey! You’ve got these things assigned to you but haven’t done anything with them for a while. Is something blocking you?” would do nicely. Right now, I send these emails, but I shouldn’t have to. Don’t be irritating with them, just send them if something is overdue by a day or two and nothing has been happening.

I work a lot with subcontractors which is great, but it’s not great, because they all have different schedules and varying commitment to the project management software we’re using for the project. Since it’s called project management software, I want it to actually manage the project, not just be a clicky to-do list timetracker.

Keep track of time for me

This might be a pipe dream, but shouldn’t there be a way to watch github commits, or file updates in dropbox (for designers saving in Photoshop). This one is probably the hardest thing to track as entire pieces of software are devoted solely to this cause, but just make a good effort.

Is this too much to ask?

To me, this seems like the bare minimum for a project management application, but it feels like such a stretch to get to this point and I’m not sure why. Keeping track of remote collaboration and asynchronous communication shouldn’t be so hard.

Freelancer personality types: Good, cheap, or quick. Pick two.

You can have it done right, cheap, or quick. Pick two.

You’ve probably heard the saying before and laughed about how it’s especially been true of some rush project you worked on, or an old code base you’ve had to revive. As a software developer, I’ve found that the statement, while true about projects, is also indicative of the type of developer I am.

Quick and Cheap

This is where I started – 3 years ago I quit my job and started freelancing. Low hourly rate, but I’d work whenever I could and managed to (barely) make ends meet. My clients got results quickly and everyone was happy except for me. Working this way taught me two important things:

Cheap clients don’t perceive value

If your client is worried about money, they either don’t value the work that you’re doing, or don’t understand the value that you’re providing them. Yes, there are budgetary concerns that should be accounted for, but the work you’ll be doing should be perceived as valuable. When you find yourself haggling over dollars, take a step back. Ask yourself, “Will the outcome of my work be worth whatever I am being paid to do?”

If the answer is no: There’s no way that the arrangement will benefit either you or your client. Walk away as gracefully as you can. If you aren’t providing good value with the work you are doing, then you are doing a bad job as a consultant.

If the answer is yes: Illustrate the value you’re creating to your client. Make sure you use ‘you’ language and write about the benefits that the project will bring. If this doesn’t work, you just need to end the relationship. Try not to burn any bridges in the process.

Speak to your client’s needs

‘You’ language is a concept I first heard about in Dale Carnegie’s classic, How to Win Friends and Influence People. Though this book is almost 80 years old right now, it contains timeless advice. If you’ve ever had trouble communicating your point of view, reading this book is your first step to fixing that problem.

‘You’ language describe your clients pains and how they’ll magically disappear, instead of talking about how you’ll use Rails and JSONs to make a robust, clean solution.

You will start to see conversations from a new perspective and be able to find ways to communicate more effectively. Specific to this situation, you’ll be illustrating the value that you’re delivering and making your clients wonder how they can pay you more!

Quality is important

I am extremely pragmatic about my code. I like to do things as simply as possible, but make sure that they are done right. Churning out poorly implemented features that have been cobbled together in a stackoverflow copy-and-paste frenzy will never result in a quality product. The next time you go to look at that section of an application, you won’t have any understanding of how it works or why it was done that way.

Striving for quality will make you a better developer. Being a better developer means that you’re saving any future developers (including yourself.) Be kind do your colleagues and do what you can to reduce the WTF moments they might have.

Cheap and Good

This is no-mans land for a freelancer. It’s a bad place to be in, because if you’re a good developer, you should be communicating how that is a benefit to your clients and charging them accordingly. Not charging enough will lead to burn out and since you still need to pay your bills so you’ll be working a lot more than necessary. Setting a sane rate is just a matter of determining what kind of value you are bringing to your client and charging accordingly.

Low rates equal less respect

Another benefit to charging more is that your opinions will hold more weight. Think about this: if you charge $300 to make a website, you will be considered to be providing the same skill level as someone’s ‘kid brother’ or nephew, or that guy down the street that’s really good with technology stuff. That’s not you. You’re not just some guy that can build a website. You’re an expert in web development and an expert demands a wage equal to their level of expertise.

All of a sudden, you’re playing a different game altogether. So, what is it that allows a freelancer to move into the Good and Fast category (notice that we’re no longer cheap?!?) Perceived value.

Good and Fast

If you are doing any software development or consulting professionally, this is the category you should fall into. There is no alternative. If your skills and expertise are not providing value for your clients, you are doing a bad job as a consultant. You’ve been hired to make your client money by increasing their profits, decreasing their costs, or handling a specific problem that would be expensive for them to deal with otherwise. You should be able to clearly state the way that you’re improving their business and how much that is worth to them.

The more accurately you can express this value, the happier your clients will be with the work you are doing for them, and the more you can charge them for it.

Here are the three reasons that your clients will pay premium rates for someone that is good and fast:

You move the needle for their profits

Whether you accomplish this by increasing revenues or decreasing costs, the main reason that any business will engage your services is that they have a problem they believe you can fix. You’re providing them with a solution, not a technological marvel. They won’t care if it’s a great codebase, unless you tell them why that is of benefit to them. In this case, TDD/best practices/maintainable code base == ‘lower total cost of ownership.’

You have expertise that can’t be found elsewhere

Another reason that clients will pay premium rates is that you’ve got expertise that can’t be found elsewhere; this is different than a value-based engagement and more akin to the laws of supply and demand.

I’ve had good success engaging larger clients who need specialty work done at premium rates. Generally these commitments pay much higher because: * you have a proven track record * there is low risk that the project will fail to be delivered within the time and budgetary restraints that they have.

These are the reasons that consulting firms can bill upwards of $800/hr to large clients. The extra cost is insurance that the job will get done.

Find the sweet spot

If you are freelancing right now, do yourself a favour and move into this category. It’s not a huge stretch to get here. You’ll be working with better clients that value your work and you’ll have more time to focus on other areas of your life.

All you need to do is take the time to learn how to practice value based pricing and begin writing all your proposals this way. This will give you a huge competative advantage when you pitch potential clients on using you for their next project.

Ember.js Concepts for Rails Developers

Moving from a full stack framework like Rails to a front end framework like Ember.js is less of a leap than you might anticipate. You’re probably already using jQuery for some elements of interactivity, but at a certain point, you came up against that wall of maintainability and ended up with a hearty serving of front end spaghetti code. Yum. Here’s where a frontend framework can help, but this can cause a different kind of confusion.

Of course, switching from Rails to a front end framework presents you with a new set of tools, many of which have the same names as the ones you are already familiar with. This really comes to a head with the issue of how responsibilities are delegated, so let’s have a Rails vs Ember.js comparison of the two frameworks to clear this up.

Origins of MVC

First, lets take a walk through history. A really quick walk.

Wikipedia tells us that the term Model-View-Controller showed up in the 1970s. Rails doesn’t follow this original definition of MVC. At this point, this doesn’t matter, because Rails is widespread and you probably make money because you know how to use it. Assuming that you’ve decided to use Ember (or other front end framework), they follow the traditional definition.

Great. Now we’re ready to go!

The Model

Here, Rails doesn’t differ too much from Ember or other frontend frameworks. A model defines a specific data structure and its relationship to other data structures. Think of a data structure as a predefined set of attributes, like a user or an appointment or a blog post, and how these things are persisted (saved to the database or whatever kind of scheme you might have cooked up).

The frameworks differ in the way that they persist things. In Rails, if you call save on an instance of a model it gets saved to the database. Cool. That’s all well and good for server side code, but what should happen when you call save on an instance of a model in a front end framework? This becomes a little more complex when you’re running client side code and can’t speak directly to your database.

Ember.js provides this through the Ember Data library. At the time of writing, Ember Data isn’t part of the standard Ember distribution, but as of 1.0.0-beta.1 (released back in August 2013), the API and core features have stabilized. This separate library makes a lot of sense, because having the client deal with the code creates a lot more decisions that need to be made.

On the client side, rather than dealing with a database interaction, we’re dealing with multiple responsibilities. Our framework needs to make requests to endpoints of the webapp, serialize data and figure out if it should be cached locally. Ember Data breaks down these responsibilities into seperate concepts, each of which is clearly defined here.

A point of clarification – If you look at the current Ember.js guides you’ll see two sections talking about models. Models is the section you want. The Object Model, just refers to Ember’s adherence to object oriented design principles (a topic for a different post, perhaps).

The View

The overall concept of the view covers the user interface, or “the stuff that the user interacts with.”

In Rails, a view is an HTML template written with some ERB or HAML to render out stuff from the database. If you’re doing it “the Rails way”, you’re probably DRYing things out with partials and maybe using helper methods or a presenter or decorator pattern. You may then sprinkle them with JavaScript to provide a rich, interactive app with a modern feel.

In Ember, there’s a fairly clear distinction between the concept of templates and views. Templates are compiled with Handlebars, and would be akin to the ERB or HAML that you’d be used to working with in Rails. Views are the logic that controls event handling behind the scenes. Generally, you won’t even need to interact with these JavaScript objects (Ember and Handlebars define them for you, intelligently) unless you’re creating a re-usable component. Ember has already pre-packaged some of these for you, including checkboxes, textfields, select and text areas. Thanks Ember.js!

The Controller

Okay, I’m not going to lie. This is where stuff gets really crazy. Hold on to your hats, we’re about to embark on a wild, mind-bending ride, but at the end of this, you’ll understand how a front end framework thinks about its controllers, and why this is so important.

The Rails Guide, Action Controller Overview, says

your controller is responsible for making sense of the request and producing the appropriate output

We’re all Rails experts here, so we know that the controller is what’s supposed to send stuff to the view template. And maybe redirect the browser. And maybe send jobs to background processing and maybe create new objects in the database or load things out of it. Boy, it sure looks like the Rails controller has a lot of stuff to do!

When dealing with a client side framework, I like to think of controllers as ‘view controllers’, because they control the view. I came to the client side framework world from Rails, so that was the easiest way for me to think about what responsibilities controllers have on this side of things. If you remember our earlier walk through history, Ember’s definition is actually more inline with the original.

That being said, what kind of responsibilities would you expect Ember’s controllers to have? Controllers will handle UI functionality that probably won’t be persisted. For example:

Let’s say that you have an option to hide items in a list. When you enable it, certain list items are hidden in the UI. You wouldn’t need to save the UI state to the database, but the controller still needs to know about it. This could be accomplished by by setting an isHidden attribute in the controller to true. The controller would pass this along to the template, which would update the UI and hide the item. So, in Ember.js, controllers act as another layer on top of a model, adding logic around how it should be displayed by the template.

However, controllers are not always backed by models. In some cases, a controller will just store attributes that pertains to a current view. The Ember docs have a great example of this pattern with the Storing Application Properties part of the controllers introduction.


As a Rails developer it’s becoming more and more necessary to have a solid grasp of at least one JavaScript framework. If you’re looking into Ember.js this knowledge should ease your transition so that you can be more effective, right from the beginning.

Rails API Testing Best Practices

Writing an API is almost a given with modern web applications. I’d like to lay out some simple guidelines and best practises for Rails API testing. We need to determine what to test and why it should be tested. Once we’ve established what we will be writing tests for, we will set up RSpec to do this quickly and easily. Basically we’ll be sending HTTP requests and testing that the response status codes and content match our expectations.

What to test?

A properly designed API should return two things: an HTTP response status-code and the response body. Testing the status-code is necessary for web applications with user authentication and resources with different permissions. That being said, testing the response body should just verify that the application is sending the right content.

HTTP Status Codes

Typical HTTP responses for a simple API on an application with authentication will generally fall within the following 4 status codes:

  • 200: OK – Basically self-explanitory, the request went okay.
  • 401: Unauthorized – Authentication credentials were invalid.
  • 403: Forbidden – The resource requested is not accessible – in a Rails app, this would generally be based on permissions.
  • 404: Not Found – The resource doesn’t exist on the server.

If you’re wondering why not just use 401 – Unauthorized or 403 – Forbidden for every permission/auth error, I’d suggest reading this stackoverflow answer. If that’s not enough, check out the W3 spec.

Response Body

It goes without saying that the content body should contain the resources that you requested and shouldn’t contain attributes that are private. This is straight forward for GET requests, but what if you’re sending a POST or DELETE request? Your test should also ensure that any desired business logic gets completed as expected.

API Testing is Integration Testing

Just like we use an integration tests to ensure that our app behaves as planned, we also require that our API responds as desired. These tests are based on HTTP requests to urls with calculated responses. For user interaction, Capybara is my testing tool of choice, but it is the wrong tool for testing APIs. Jonas Nicklas (creator of Capybara) wrote Capybara and Testing APIs to explain why you shouldn’t use it.

“Do not test APIs with Capybara. It wasn’t designed for it.” – Jonas Nicklas

Instead, use Rack::Test, rather than the Capybara internals.

Use RSpec Request Specs

Since we’ve established that we’ll be using Rack::Test to drive the tests, RSpec request specs make the most sense. There’s no need to get fancy and add extra weight to your testing tools for this.

Request specs provide a thin wrapper around Rails’ integration tests, and are designed to drive behavior through the full stack, including routing (provided by Rails) and without stubbing (that’s up to you).

To test requests and their responses, just add a new request spec. I’ll demonstrate testing a user sessions endpoint. My API returns a token on a successful login.

# spec/requests/api/v1/messages_spec.rb
describe "Messages API" do
  it 'sends a list of messages' do
    FactoryGirl.create_list(:message, 10)

    get '/api/v1/messages'

    expect(response).to be_success            # test for the 200 status-code
    json = JSON.parse(response.body)
    expect(json['messages'].length).to eq(10) # check to make sure the right amount of messages are returned

This works exceptionally well for get, post and delete requests. Just check for the status code you want, and that the response body is as you expected. That being said, with this setup we’ll be doing json = JSON.parse(response.body) a lot. This should be a helper method.

Add JSON Helper

To DRY things out for future tests, pull the json parsing logic into an RSpec helper. This is what I’ve done:

# spec/support/request_helpers.rb
module Requests
  module JsonHelpers
    def json
      @json ||= JSON.parse(response.body)

And then add the following line inside the config block of spec_helper.rb

RSpec.configure do |config|

  config.include Requests::JsonHelpers, type: :request


Now we can remove any of the JSON.parse(response.body) calls within our tests.

Let’s have another example spec, this time getting a single message.

# spec/requests/api/v1/messages_spec.rb
describe "Messages API" do
  it 'retrieves a specific message' do
    message = FactoryGirl.create(:message)    
    get "/api/v1/messages/#{message.id}"

    # test for the 200 status-code
    expect(response).to be_success

    # check that the message attributes are the same.
    expect(json['content']).to eq(message.content) 

    # ensure that private attributes aren't serialized
    expect(json['private_attr']).to eq(nil)

Okay – you’re done. Keep this in mind when you’re building out your api, and you’ll be golden. I promise. If you need some more info on how to set up your app as an API, I’d highly recommend this article: Building a Tested, Documented and Versioned JSON API Using Rails 4

Ember.js Routing and Rendering Simplified

Last week we quickly scaffolding an Ember.js application using Yeoman. That’s great, but it’s hardly useful to have an app that displays a list. I can write HTML that does that just fine, thanks very much. So, what’s useful here? Why bother with a client side framework at all? In this Ember.js tutorial, I want to do something that shows off WHY you’d do this in Ember, rather than with Turbolinks and a sprinkling of JavaScript. At the end of the tutorial, you’ll understand enough about Ember to do something useful with it.

As web developers, we all know that the internet is basically a series of text, pictures, buttons and text fields that we put stuff into and look at. Our job is to facilitate these types of interactions for our users; by making them quick and pleasing we will leave the people using our products feeling satisfied. That means that we must use JavaScript. The traditional approach is to augment static pages, but using a client side framework like Ember or Angular allows this work to happen quickly, while creating a maintainable code base. To demonstrate how ember.js handles routing and rendering views, we’re going to create a user profile editor.

If you’d like to follow along, make a new directory called users and initialize an ember.js app with yeoman in that directory. If you need more information on how to do this, get started with Ember.js in 5 minutes and then meet me back here.

With our initialization of the app, Users will be the global namespace that everything happens in.

View Templates and {{outlet}}

We need to set up a space for our sidebar navigation, and a main area where our logic will go. To do this, open up app/templates/application.hbs and change it to look like this:

  <div class="container-fluid" id="main">

Don’t worry, we’ll be adding back the navigation logic in the next step, but here its important to concentrate on {{outlet}} and what its meaning is. The default hierarchy of template rendering works by first rendering the overall application template which we’ve specified in application.hbs; the call to {{outlet}} specifies where the template that is specific to the current page will be rendered.

The default route – Index

Even if you haven’t done anything in your application yet, Ember provides you with a few basics without you even having to touch any code. By adding a resource to the application’s router, Ember will look for the associated route logic, the controller and the view template. If it doesn’t find the route logic or the controller, Ember.js will automatically generate these for you. Out of the box, without adding any code, visiting your root url goes through the following actions:

  • The ‘index’ route name is visited, this passes the request to
  • The IndexRoute namespace route logic, which is auto generated if it’s not present
  • The IndexController, (also auto generated) then handles the view template rendering of
  • A template with the associated name – in our case index.hbs

This is an outline of the four most simple steps of a request in an Ember.js application.

For this example, we want to set up our index template to render a list of users in a navigation panel on the left. Edit app/templates/index.hbs to look like this:

<div class="row-fluid">
    <div class="span3">
      <div class="well sidebar-nav">
        <span class="nav-header">Users</span>
        <ul class="nav nav-list">
    <div class="span9">

If you’ve scaffolded your application using Yeoman, then running grunt server will show you a page that looks like this:

basic user navigation

Boring, but it’s a start..

Great, okay, so, we have a basic place where we could render a list of users to click on and a nested {{outlet}} – this is where we’ll render a user profile.

Rendering Data

Adding data to Ember is simple using the ember-data library. Right now, the library is under HEAVY development, but for our purposes here, version 0.13 does the trick nicely. We’re going to add a User model and some user fixtures to render since we’re just demoing some front end features.

Our first step will be to add the user model.

// app/scripts/models/user.js
Users.User = DS.Model.extend({
  firstName: DS.attr('string'),
  lastName: DS.attr('string'),
  administrator: DS.attr('boolean'),

Fixtures are built in to Ember-data. To add them, we’ll just configure our data store.

// app/scripts/store.js
Users.Store = DS.Store.extend({
  revision: 1,
  adapter: 'DS.FixtureAdapter'

We’ll also have to tell yeoman to load this file by adding the following to app/scripts/app.js:


You might notice the revision attribute. This just represents the revision of the API that you’ll be communicating with, which, in our case is meaningless. Right now this is required, but I’m assuming that with development, Ember-data will just handle this automatically. Specifying DS.FixtureAdapter just means that we can add user fixtures and Ember.js will treat them like they’ve come from a web service. Let’s do that. Add the these fixtures to the bottom of app/scripts/user.js

Users.User.FIXTURES = [
    id: 1,
    firstName: 'Tom',
    lastName: 'Dale'
    id: 2,
    firstName: 'Matthew',
    lastName: 'Lehner'

Great – we’ve got some users. If you’d like to test it out, just type Users.User.find(1).get('firstName') into your browser console and you can see that the response is this:

Found Tom.

Finding records with ember-data.

Rendering our data

So, here comes the good stuff. Finally we get to make a view render something interesting, other than static HTML. How do we do this?

First, we have to find this data. The route for the specific view will specifies which data is rendered in the template. To do this, we add the following logic to app/scripts/router.js:

Users.IndexRoute = Ember.Route.extend({
  model: function () {
    return Users.User.find();

This tells your ember.js app that the index route (remember, that’s the default route for the ‘/’ url) is dealing with the data found in the Users.User model. Now we’ll tell the template in app/templates/index.hbs to render the users for us. Add the following handlebars logic inside the <ul class="nav nav-list"> tag:

{{#each controller}}
  <li>{{firstName}} {{lastName}}</li>

Refresh your page, and suddenly we’re looking at a list of users!

List of users.

The users are rendering, just fine!

Doing something useful – Adding a UI for editing.

So now that we’ve done a lot of work to create a list, lets do something useful with it. We’ll make the side bar into a navigation piece. Clicking on a user will display a form for editing their profile. There are two steps to this, we need to add a nested resource to the index route and tell the view template what to render.

Add the following to app/scripts/router.js:

Users.Router.map(function () {
  this.resource('index', {path: '/'}, function () {
    this.resource('user', { path: '/:user_id' });

Users.UserRoute = Ember.Route.extend({
  model: function (params) {
    return Users.User.find(params.user_id);

update the list items in app/templates/index.hbs to link to each user resource:

  {{#linkTo 'user' this}}
    {{firstName}} {{lastName}}

and the following view template to app/templates/user.hbs:

  <h1>Editing {{firstName}} {{lastName}}</h1>

    <div>{{view Ember.TextField valueBinding='firstName'}}</div>
    <div>{{view Ember.TextField valueBinding='lastName'}}</div>

And now we have editable users and thanks to Ember.js and Handlebars data binding implementation, wherever an attribute is rendered on the page, it will automatically change when edited. Try it out!

User edit screen

Since this Ember.js tutorial is about routing and rendering views, lets examine what we’ve accomplished with this last step. You can see we’ve nested the user resource under the index route; because it’s nested, this will automatically render to the {{outlet}} in our index template.

Nested Views

Any web application that you’ll be creating will have different requirements for certain sections – perhaps a widget that gets rendered everywhere or a portion that changes based on state. With Ember’s handling of nested routes, you get these page areas automatically. Remember how our index.hbs template has another {{outlet}}? Well, that’s where any resources that are nested under the index action will be rendered. You can have nested routes for anything that’s associated with users such as activity, edit, show, profile, friends, etc. and they will automatically render where you specify the outlet on the main user template.

Data binding

Another benefit of Ember is that the data binding keeps all of the associated attributes updated everywhere they’ve been rendered. There’s no lag between editing a user name, and that user’s name showing up the way it’s been changed.

This guide to Ember.js routing and rendering is really just touching on the basics of routing and rendering within the framework. Each JavaScript MVC framework has its own unique paradigm to how development should be done and I find it helpful to start with a good foundation. From here, you can start building out a more complicated application that consumes an API, has animated elements and a user interface that responds instantly.

Get started with ember.js in 5 minutes

Recently there’s been a lot of discussion around different JavaScript frameworks such as Angular, Ember, Backbone with Marionette. After years of JS spaghetti code and memory leaks, these frameworks solve many pain points previously felt when building JavaScript applications. There are now great development tools that help to quickly get started creating responsive, single page applications with a maintainable codebase. Having rolled out a number of Backbone apps, I’ve been interested to see how well Ember works in comparison. Here we’re going to spend a moment with ember.js and Yeoman.

Before we start, you must have node installed and configured correctly. If not, install it and then come back.


Yeoman is an intelligent collection of tools that make developing JavaScript applications pain free (or at least less painful.) This is how we will be quickly scaffolding our application, installing its dependencies and running a development server to view the application.

In addition to the things we’ll be covering here, Yeoman will build/minify your app for production and run its test suite. See yeoman.io for more information.

Installing Yeoman

To install Yeoman and the generators for an Ember application, simply run:

npm install -g yo
npm install -g generator-ember

This will install the current version of Yeoman (rc1) and the Ember generators (0.5.9). Great! Now we’re ready to get going.

Creating The Ember.js App

Create a new directory for the application and switch into it:

mkdir ember-demo
cd ember-demo

Running yo ember from the command line will give you a menu similar to this: yeoman menu for ember.js generator

Say yes to the following options:

  • Would you like to include Twitter Bootstrap for Sass?

Following this, Yeoman will scaffold out an Ember app and automatically install its required dependencies by running bower install and npm install.

Once this is done, all you need to do is run

grunt server

This will open a web browser with your app which should look something like this: Ember.js start page

with the following info available in your browser’s console: Yeoman_Ember_Starter_Kit-3

So, great, we’re now running a very simple Ember app. Wasn’t that easy?


If you’re having any trouble with this tutorial, make sure you have the latest versions of Yeoman and generator-ember installed – it’s simple to update them: npm update -g yo generator-ember

The Results

This may look simple, but there are a few interesting things going on.

The page is generated dynamically by Ember – have a look in app/index.html – you’ll see that there’s no markup, just a bunch of required scripts. Here’s where the magic is happening.

If you look in app/templates, you’ll see application.hbs and index.hbx. Two handlebar template files that are telling Ember what to render. The three colours are coming from data stored in scripts/app.js.


You can see that the colors printed on the index page are defined here in the array. Add another item to the array, and the page will list that.

App.IndexRoute = Ember.Route.extend({
  model: function () {
    return ['red', 'yellow', 'blue'];


Here’s the handlebar template that is used to render those items. Very simple, but a good illustration of how you can use handlebars to loop through an array.

<div class="hero-unit">
  {{#each item in model}}


Using Yeoman, Bower, and Grunt is a great way to quickly scaffold the barebones for a new JavaScript program. In less than 5 minutes, you can go from nothing, to a basic framework to start building out your application.

Updated July 16, 2013 updated instructions for generator-ember 0.5.2

Updated July 19, 2013 updated instructions and screenshots for generator-ember 0.5.7

Updated July 27, 2013 generator-ember 0.5.9 and yeoman 1.0.0-rc.1.3

Reproducing iOS 7 Parallax Backgrounds with JavaScript and CSS

The unveiling of iOS 7 has brought a lot of focus onto whether or not the design direction that Apple has chosen to take has been the right path. In this article we’re focusing on reproducing the parallax background effect used to ‘create a whole new experience of depth’ (as Jony Ive puts it). The effect is demonstrated in the iOS 7 video at the 2:45 mark. When you tilt your iOS device, the background moves slightly while the foreground elements stay fixed. This creates an effect which separates the two plains and gives a slight illusion of three dimensions.

iOS 7 Background Parallax

To reproduce this in a web browser, we’re required to tap into the device’s gyroscopes and accelerometers through the deviceorientation event. Luckily, modern browsers have enabled this API. On mobile platforms, this will be available in the following versions browsers: Safari 4.2 and  Android Browser 3 (or greater.) On the desktop, only Chrome and Firefox support it. For simplicity, this demo only supports webkit browsers (Safari, Chrome, Android) as the implementation is currently different in FireFox.

The `deviceorientation` Event

To get information about how the device is positioned in space, we need to watch the `deviceorientation` event. This event will return values which will tell you how far the device is leaning and which way it is pointed, if the device has a compass. The returned values are: beta, the side-to-side value, gamma, the front-to-back value, and alpha, the compass direction. A basic example of listening to the `deviceorientation` data is as follows:

window.addEventListener('deviceorientation', function(eventData) {
  // The compass direction - will return a value between 0 and 360

  // Side to side value - will return a value between -180 and 180

  // Front to back value - will return a value between -90 and 90

Using this data, we will move the background around to create the same effect as in iOS7. First, we need to set up a container with the background that is the same size as the device. In this example, we’re using an iPhone 5


<div id='background'>
  <div id='foreground'>
    Content for the foreground


We’re using a non-repeating background asset from iOS7. The important thing here is to make the actual background image larger than its container, and then we manually center it with the ‘background-size’ and ‘background-position’ attributes. With a repeating background, this step can be skipped.

#background {
  margin: 0 auto;
  padding-top: 100px;
  height: 568px;
  width: 320px;
  background-image: url('background.png');
  background-size: 360px 608px;
  background-position: -20px -20px;

#foreground {
  text-align: center;
  padding: 20px;
  background: rgba(255,255,255,0.2);
  border-radius: 18px;

Finally, the JavaScript

var background = document.getElementByID(‘background’);

window.addEventListener('deviceorientation', function(eventData) {
  // Retrieving the front/back tilting of the device and moves the
  // background in the opposite way of the tilt

  var yTilt = Math.round((-eventData.beta + 90) * (40/180) - 40);

  // Retrieve the side to side tilting of the device and move the
  // background the opposite direction.

  var xTilt = Math.round(-eventData.gamma * (20/180) - 20);

  // Thi 'if' statement checks if the phone is upside down and corrects
  // the value that is returned.
  if (xTilt &gt; 0) {
    xTilt = -xTilt;
  } else if (xTilt &lt; -40) {
    xTilt = -(xTilt + 80);

  var backgroundPositionValue = yTilt + 'px ' + xtilt + "px";

  background.style.backgroundPosition = backgroundPositionValue;
}, false);

A working demo is available here - it’s best viewed on an iOS device, but will work on Android as well. Tip your device around to see the effect (it’s a bit subtle).

A Working iOS 7 Parallax Style Background

While performing this test, I noticed that Android devices return strange values when turned from side to side, going from 0° to 270° in when turning over to the right and 0° to -90° and jumping to 270° when turning over to the left. Don’t ask me why this is a thing that happens, it’s flabbergasting even to me.

Further resources

How I started a 6 figure, single person consultancy while learning to code

2 and a half years ago I quit my job.

It was a good job, and compared to my peers, I was doing really well. The problem was, the  non-profit organization I worked at had contracted a small Rails consultancy to build a web app that consolidated some of the business processes. They billed $120/hour while I made $21/hour to manage the project.

I loved the role. I got to shape the way that my co-workers’ lives functioned every day, giving them a tool that was vastly superior to the spreadsheets and badly designed access databases they used. Everything was in one place and productivity soared!

The problem was this – I made the product. I didn’t write the code, but I functioned as the product manager, shaping the user experience and making sure that the edges were polished. Because it was ‘mine’, I wanted to keep working on it, but as the project neared completion the consultants we had hired were looking to wind down their shop. We needed a replacement.

At the outset of the project, the developers asked me to sign up for a GitHub account. I watched their commits and when I would ask them to change something and I would see the changes that happened. It looked like HTML and CSS, with a bit of  extra stuff inside of these other ‘special’ tags that looked like this: <% %>

I had a realization. I had taught myself to build websites in the past; this meant that I could teach myself learn to build web apps and building web apps is a skill that commands a $120/hour billable rate.

I set to work to develop this skill set. After 6 months of reading Ruby books, doing Rails tutorials and trying things in the browser. I sent my first pull request and it was merged into the project. Success! I was a developer and I was addicted to the unlimited opportunity to learn more. Shortly after, in February 2011, I quit my job and was retained on contract to work on the app.

February was a scary month. I had one client and no savings to speak of. I knew that I needed to hustle to get enough money to pay my cost of living. At the time, this was about $1300 minimum. I started my search on google for rails developers in the area, hoping that there would be a meetup or somewhere I could interact with local web people. There was nothing, but one day, by chance, I met someone who ran a local web development shop. One of the baristas at a coffeeshop I frequent told me who he was and where he worked. I went to introduce myself.

“Hi, I’m Matthew. I’m a Rails guy and figured I should introduce myself to you.” This worked out pretty well – he gave me my first contract as an independent for a mobile site built with backbone. Prior to this, I had very limited exposure to Javascript, but 8 weeks later, and $4000 richer, I was writing reasonable object oriented code in it. Essentially, this was a $4000 pay-cheque to fund my time spent learning Javascript.

Because I was writing for underpowered mobile platforms, I was required to learn good javascript practices for memory usage and speed. While the amount I made, per hour, was significantly lower than the pay at my previous job, at the end of the contract I knew that I could teach myself any other tools that I needed to be an excellent web developer. And be paid to learn.

I learned to say yes. When an opportunity arises that will take you in the direction that you are interested in, say yes. Even if you’re not currently equipped to deliver it, you can pick up the knowledge and tools along the way.

Following this first contract, I realized that I just needed to tell people about what I did. Over time, new contracts materialized out of this process. For the next year, I kept working, kept learning and kept trying to meet more people this behaviour has yielded the greatest growth to my consultancy.

I have made a lot of mistakes along the way and the process has been difficult at times but now, at two and a half years in and I’m through the worst of it and am running a successful freelancing business that brings me a monthly 5-figure income.

Next week, I’ll be giving out my top 4 tips for first time freelancers. If you are a freelancer or are thinking of making the switch this advice will save you time and money.

Caveat: I know the title of this post will generate some questions, so I want to say that getting to a point of generating a 6 figure income took more than one year of running the consultancy, but it didn’t have to.