<!-- Content Here -->

On Building an API

A few months ago we announced the availability of the Lionbridge onDemand Public API. While there are many translation APIs in the marketplace, I think that ours is the most comprehensive. Most translation APIs offer one level of translation quality (for example, machine translation or crowd translation or professional translation). The onDemand API allows you to select a translation type that meets your needs. This means that you can integrate with one API and give your customers lots of options. We also support many different content types. For example, we can translate videos as well as basic documents. Lastly, we offer different payment options. The end customer can pay themselves or the money can flow through our integration partner. I think these differentiators are responsible for the rapid adoption we are seeing. We already have around ten third party integrations in production or nearing completion.

Personally, this has been a huge learning experience. While I have used many APIs and even helped developed a couple, this is the first time that I designed one from a blank page. The sheer number of approaches, options, and details that you face is enormous. And although the biases formed from personal experience are important, what really matters is the developer audience — not just in the decisions you make but also how you support them.

I hate the term best practice but here are some of the things we got right. I must admit that we didn't always land on all of these practices the first time but when we adopted them, we definitely saw results.

• Learn from others. When first designing the API, I drew inspiration from other APIs that I liked to use. I also found great information from George Reese's The REST API Design Handbook.
  
• Get feedback. When first designing the API, I had the benefit of knowing who the first customers would be. I wrote the initial specification in a Google Doc and invited feedback. The first partners caught some important omissions and had some great ideas too. I also had different developers review the specification before development started.
  
• Be pragmatic about change. An API is a contract. It shouldn't change. However, in the early going there were a few cases where it made sense to change the specification. This was inconvenient and awkward for developers who are starting their integrations. However, it was much less painful than making changes later when the install base is bigger and changes would break working systems. Managing these changes requires a lot of humility (admitting you are not perfect) and effort to rebuild trust. Once the lead integration partner was getting close to being feature complete, however, we did lock down the version of the API and saved our changes for subsequent versions. Since the initial launch of the API to our beta partners, we have launched another version and are now working on a third. We handle versioning with an HTTP header so it is easy for a client application to update the version to get access to the new feature.
  
• Hire your first client. While any early beta customer will need to accept some level of instability, you don't want to risk a partnership with your earliest growing pains. For this reason, we hired a contract PHP programmer to develop and test code samples for working with the API. This external developer had no more access than a true partner developer would have. The experiences of this developer gave tremendous insight. It exposed ambiguity in the documentation where the API implementer interpreted different meaning than an external reader. It revealed cases where the test passed but externally developed code didn't work.
  
• Give client developers a plan of action. Like with most API's the hardest part of working with the onDemand API is authentication. For this reason, we recommend a development sequence that starts with the easiest API: List Services. We also wrote up a quick tutorial with a code sample to help. For our beta developers, we created a project plan template that developers could follow. It contained tasks for integrating with the various features and rough time estimates. I was surprised to learn how much the developers liked this. Personally, I hate being given a project plan that I had no input over.
  
• Provide fanatical support. Even though I love software development, I am the first to admit it can be frustrating. It is easy for developers to get bogged down and stuck. The smoothest implementations we have had were when the dev team actively engaged the client developers. I admit that sometimes I felt like my time was being stretched too thin. But when you think about it, how can you get more leverage than helping a partner use your service and bring you business? I also enjoyed working with external developers. First of all, they are savvier than regular business users so you can rule out silly things like being disconnected from the Internet. Second, it was fun to troubleshoot with them as they sent requests and we inspected what onDemand received. Pinpointing errors can save a client developer a lot of time. This work had the side benefit of improving our error handling to provide more informative responses.
  
• Treat your development sandbox like production. This should sound obvious but a lot of services that I have integrated with have very unstable developer sandboxes. They are not always available and they have issues that you don't see in production. There is nothing more frustrating than trying to fix your code and realizing that the problem is in an external system you are integrating with. For this reason, we manage the sandbox as a production environment. It gets the same monitoring as a production environment and we release new code to sandbox after it has been in production for a couple of days.
  
• Test like you mean it. Software is incredibly picky about the slightest detail so API testing needs to be extremely thorough. You can't just verify that you are getting data back. The data you get back needs to be precisely like what is in the documentation. For this reason we do what I call double-blind testing. The development team writes tests that run whenever new code is merged into the integration branch. An external QA team writes and runs tests based on the documentation whenever we have a release candidate. The hope is that having two independent approaches will everything. When it doesn't, we have a major debrief.

If you do it right, an API can revolutionize your business by opening channels that extend your reach. But getting it right requires commitment and attention to detail. If you underperform in any aspect (design, implementation, or support) your program is doomed. You won't always get everything right but if you maintain your focus and address your failures, you can get things back on track.

Mobile Pet Peeves

Now that I sorted out this site's mobile problems, I feel authorized to complain about mobile issues on other sites. Here are my top four pet peeves.

1. 
   

   Aggressive App Promotion

   
   

   “I’d LOVE to download your app instead of going to the webpage I just tried to visit!”— No-one, ever. No-one in the future either.

   — Graham Linehan (@Glinner) July 10, 2012

   
   
   

   You go to a site and get blocked by a dialog box that encourages you to download their app. When I click on a link or type a URL, I am sending a pretty clear signal that I want the content that is on the other end. I am not looking for another app to install.
   

   
   

   If you want to promote your app, use a banner ad slot to make a subtle suggestion. Don't put up an interstitial that breaks the flow. A few sites do this nicely by putting a small floating tab on the bottom right of the page.

   
   


2. 
   

   Dialog Boxes

   
   

   Speaking of dialog boxes, don't put them on your mobile website at all. If you feel like you need a dialog box, make sure to design it for mobile by making the buttons extra big. Those tiny x's in the corners just don't cut it.

   
   


3. 
   

   Flash

   
   

   The writing has been on the wall for a long time now and, now with Android Jelly Bean dropping Flash support, there is no denying it. Flash is dead on mobile. Don't use it — especially if your site is for a restaurant or any other destination for people on the go.

   
   


4. 
   

   Disjointed Mobile/Full Experience

   
   

   If your content is any good, it will be shared between users on all sorts of platforms. Someone might first encounter the content on a mobile device and then want to continue reading on the full experience. To facilitate this, make it easy for a user to jump between content views.

   
   

Why the Redesign?

Astute observers of this blog have probably noticed that I redesigned the site. Being someone who agrees with Lou Rosenfeld when he says Redesign Must Die, this wasn't as capricious a decision as it may seem.

So why the redesign? Two reasons really. First, since joining Lionbridge this site is no longer for selling consulting services. It has gone back to its roots as a blog. I wanted to move away from the Content Here, Inc. company branding and get it back to a personal blog. Second, and more importantly, I wanted to experiment with adaptive design. Over the past year, a growing proportion of my traffic has been from non-desktop devices (phones and tablets). Reading the site was rough on a little screen. And that plays into a larger philosophy of minimalism — keeping as little as possible between the reader and the content.

As an experiment, I downloaded a very basic theme (Backbone) and didn't customize the code at all. I just played with the configuration options. I also benchmarked the site using Sitebeam, which applies 40 tests. After a bit of tweaking, I was able to increase my total score from 5.6 to 6.9 out of 10. The greatest improvements were in accessibility (from 6.0 to 7.3) and technology (4.6 to 6.0). There were also improvements in the content and marketing categories (see screenshot).

It remains to be seen if these scores reflect real usability and utility improvements. Anecdotally, I think the mobile version is much better. The content stands out and is easy to read. That was the result that I was going for. More importantly, I want to hear from you. Please provide feedback in the comments, Twitter (@sggottlieb), or Google Plus.

Why you should do your homepage wireframe last

When building websites, I always recommend developing the home page last because the purpose of the homepage is to highlight content within the site. You need build out the site so you have something to highlight before you build the homepage. Over the past year, I have started to realize that the same advice holds true for design. In fact, I now feel even stronger about that rule for design. Here are four reasons why.

1. A homepage wireframe doesn't tell a whole lot.

   Wireframes are helpful to express content structure and site functionality. When I look at a wireframe, I see a content model (what elements make up a particular type of content) and features (how the visitor interacts with the content — commenting, voting, sharing, related links, etc.). The home page is more of a summary. You don't see that level of detail. The things that matter to a homepage (branding elements like font, imagery and palette) are not even captured in a wireframe. Talk about those things near then end of the project because you can make sweeping visual changes by editing a few lines of a style sheet.

2. The biggest functionality decisions are in the inner pages of the site.
   Although you may think you have scoped the project during your requirements phase, the devil is in the details. How the functionality works will have huge implications on project cost. The sooner you have those conversations, the sooner you will be able to adjust budget and scope so you can spend resources cost-effectively. Leave those decisions to the end and everyone gets surprised ... in a bad way.

3. Internal audiences care more about the home page than external audiences do
   Let's face it, if your site is like most sites, most of your traffic is coming from search engines and link sharing (Twitter, Facebook, etc.). If you have something worthy of your audience's attention, Google is going to know about it and take your visitors directly there. The homepage doesn't do much more than give a visitor something to look at when he doesn't know where to go. The homepage is more about corporate vanity than serving audiences.

4. It is easy to get bogged down in political issues that have nothing to do with the functionality of the site.
   While there is very little functional substance on the homepage, that doesn't mean people can't argue about it. If the homepage is treated as a symbol for what is important to an organization (which it often is), a design session will quickly degrade into a turf battle. Your designer will try to mediate, but there is no way he will be able to settle such a fundamental argument. Don't waste time arguing in the beginning of the project when there is so much productive work to be done.

Unfortunately, I regularly meet resistance from designers who habitually begin with the homepage. I understand the temptation. On the surface, a homepage wireframe seems easy and uncontroversial. It is just a bunch of blocks on the page that stakeholders can privately fill with their imagination; there are no assertions on how major site features behave. But, from a technical design perspective, we don't learn anything from the homepage wireframe. We can't start thinking about content structure and end-user functionality that will have major implications in scope and planning. The longer we delay that work, the greater project risk.

Developers and Designers

A few months ago I read Lukas Mathis' through provoking essay "Designers are not Programmers" where he makes the case for a separation between designers and developers. To summarize his argument, thinking about implementation details distracts the designer from the user and results in applications (and websites) that are easy to build but hard to use. He makes a very thorough case (you should definitely read the full essay) but something just doesn't sit well with me. In my practical experience, I find that teams are more efficient when roles overlap and people understand what is happening outside of their silo. Here are some reasons why:

• A designer is often faced with lots of options of how to solve a user problem. When it is a coin toss between two solutions, why not choose the one that is easier to implement and apply the time and effort saved to something that really needs the additional complexity?

• The static tools that pure designers use (e.g. photoshop) have no way to express interactive functionality. All the details that the developer needs to know need to be captured in some sort of specification that can never be complete and is usually out of date. Making the developers wait until the specification is done is inefficient.

• Good software cannot be achieved by brilliant designers alone. It takes iteration and feedback to get it right. A cold hand-off between the designers and developers lengthens the iteration cycle (so you get fewer of them in a fixed amount of time and budget) and creates more of an opportunity for information loss.

In an ideal world with infinite time and money (and omniscience too), it might be better to have designers whose minds are unencumbered by knowledge of implementation details. Anything that they dream of can be implemented... with enough time and resources, of course. But I don't live in that world. In the world I live in, product managers and publishers have to make lots of compromises. They also need to be able to react efficiently to correct bad design decisions so that the product (or website) can continually improve. For that, you need an agile team that solve problems directly. this means staying out of a designer-only loop.

The most effective teams that I have worked on have all had a talented front end developer that can rapidly design in DHTML (leveraging javascript libraries and CSS) and knows enough server side scripting to make most user interface changes unassisted. With this mix of skills, it is truly amazing how quickly a small team can get a product in front of users where it can be improved by feedback.