BlogmyQuery – BMQ

In part one of this series, we looked at the consequences of designing and developing software in isolated environments. Some people work in lonely silos where no process exists, while others work in functional silos where too much (or the wrong) process makes innovation and progress difficult.

So, how do we break down the artificial walls that keep us from creating great things together? How can organizations foster environments that encourage natural, unforced collaboration?

There are no quick fixes, but these are far from insurmountable problems. I propose the following five-level hierarchy as a solution:

There are no shortcuts to breaking down silos. You can’t fix the environment if the organization doesn’t understand the problem. You can’t improve the development process if the right environment doesn’t exist to enable healthy guidelines. You have to climb the pyramid brick by brick to the ultimate goal: better software through true collaboration.

Let’s look at each of these levels.

Level 1: Make Sure Everyone Understands The Problem

Photo credit: TransGriot

Most organizational leaders would probably admit that collaboration is not as good as it should be, but they might try to solve the problem incorrectly. As Louis Rosenfeld recently said in “The Metrics of In-Betweenness�:

Many senior leaders recognize the silo problem, but they solve it the wrong way: if one hierarchical approach to organizing their business doesn’t work, try another hierarchy. Don’t like the old silos? Create new ones. This dark tunnel leads to an even darker pit: the dreaded — and often horrifically ineffective — reorg.

The first level is admitting that there’s a problem and that the current problem-solving methods just aren’t working. This isn’t about moving branches of the organizational tree around. It’s about planting the tree in more fertile ground to establish the right foundation in order to start looking for solutions.

Level 2: Empower Teams To Do Great Work

Once the organization is united around a common understanding of the problem, then the starting point for breaking down silos is to take a healthy look at the culture and work environments. Above all, the needs of makers (such as designers and developers) should be taken seriously by managers (those who direct and enable the work). Mike Monteiro takes on this issue by attacking the calendar in “The Chokehold of Calendars�:

Meetings may be toxic, but calendars are the superfund sites that allow that toxicity to thrive. All calendars suck. And they all suck in the same way. Calendars are a record of interruptions. And quite often they’re a battlefield over who owns whose time.

Paul Graham takes a more holistic view in “Maker’s Schedule, Manager’s Schedule.â€� He explains that managers break their days up into hour-long stretches of time, while makers need large blocks of time in order to focus:

When you’re operating on the maker’s schedule, meetings are a disaster. A single meeting can blow a whole afternoon, by breaking it into two pieces, each too small to do anything hard in. Plus you have to remember to go to the meeting. That’s no problem for someone on the manager’s schedule. There’s always something coming on the next hour; the only question is what. But when someone on the maker’s schedule has a meeting, they have to think about it.

Makers need long stretches of uninterrupted time to get things done, and get them done well. Most siloed environments don’t support this because of an insatiable need for everyone to agree on everything (more on this later). So first, helping managers understand why this is such a big deal for makers is important, so that the managers can effect cultural change.

Michael Lopp talks about this in his article “Managing Nerds.� Substitute the word “nerds� in this article with “designers and developers� (no offense intended). Michael describes how nerds are forever chasing two highs.

The first high is unraveling the knot: that moment when they figure out how to solve a particular problem (“Finally, a simple way to get users through this flow.â€�). But the second high is more important. This is when “complete knot dominationâ€� takes place — when they step away from the 10 unraveled knots, understand what created the knots and set their minds to making sure the knots don’t happen again (“OK, let’s build a UI component that can be used whenever this situation occurs.â€�).

Chasing the Second High is where nerds earn their salary. If the First High is the joy of understanding, the Second High is the act of creation. If you want your nerd to rock your world by building something revolutionary, you want them chasing the Second High.

And the way to help designers and developers chase the second high is to “obsessively protect both their time and space�:

The almost-constant quest of the nerd is managing all the crap that is preventing us from entering the Zone as we search for the Highs.

So, how do you change a culture built around meetings and interruptions? How do you understand what designers and developers need in order to be effective, and how do you relentlessly protect them from distractions? Here are two ways to start:

1. Ask the makers what’s missing from their environment that would help them be more effective.
   Find out what your designers and developers need, and then make it happen. A quiet corner to work in? Sure. A bigger screen? Absolutely. No interruptions while the headphones are on? Totally fine. Whatever it takes to help them be as creative as possible and to be free to chase that second high.
2. Start working on a better meeting culture.
   This one is a constant struggle for organizations of all sizes, and there are many ways to address it. I try to adhere to two simple rules. First, a meeting has to produce something: a wireframe, a research plan, a technical design, a strategic decision to change the road map, etc. Secondly, no status meetings. That’s what Google Docs and wikis are for (agile standups are an exception to this, for reasons best left to a separate article).

Level 3: Create A Better Design And Development Lifecycle

Once a team is optimized for creativity, then it becomes possible to build appropriate guidelines around that culture to take an idea from vision to shipped product. This includes the development process as well as the prioritization of projects, so that you only work on things that are important.

The Design And Development Process

Formalizing the design and development process is so critical: from the identification of user, business and technical needs, to the UX design cycle, to technical design and, ultimately, to development, QA and launch. By formalizing this process based on a common understanding of the needs of the business, the team will have no excuse for skipping the UX phase of a project because “it would take too long.� By providing different scenarios for whatever timelines are available, the team ensures that design and UX always remain a part of the development lifecycle.

But one particular aspect of the development process has a direct impact on organizational silos: ensuring the right balance between design and engineering, and how designers and developers work together. This isn’t explored enough, yet it can have far-reaching implications on the quality of a product.

Thomas Petersen describes the ideal relationship between designers and developers in “Developers Are From Mars, Designers From Venus�:

They are the developers who can design enough to appreciate what good design can do for their product even if it sometimes means having to deviate from the framework and put a little extra effort into customizing certain functionality. If they are really good developers they will actually anticipate that they have to deal with it and either use a framework that allows them be more flexible or improve the framework they prefer to work in.

And they are the designers who learn how to think like a programmer when they design and develop an aesthetic that is better suited to deconstruction rather than composition. They know that composition in the Web world is not like composition in the print world and that what they are really doing is solving problems for customers, not manifestations of their creative ego.

Beyond the usual discussion of whether designers should be able to code, one of the main causes of bad blood between the groups is that developers are rarely asked what they need in order to write the best possible code. Designers should always ask their development teams two questions:

1. “How would you like to contribute to the product development process?�
   It is amazing how few people actually ask this question, as is how the opinions of the people who understand the product at its most detailed level often don’t have a voice in ideation or prioritization. Any cycle that doesn’t include developers from the beginning will likely fail, because the conflict between design and utility cannot be resolved with detailed specifications. It can be resolved only around a table, with plenty of paper to draw on and time to argue about the best way to do things. Of course, designers need time on their own to create, but developers need to be given a chance to contribute to the product that they’re building in a way they’re comfortable with.
2. “What information do you need to start coding?�
   The theoretical discussion about low-fidelity versus high-fidelity mock-ups or prototypes is largely misguided when it comes to real-world development. The goal is right-fidelity specifications, and that all depends on the maturity of the application you’re working on and the style of the developer. Some developers need perfect PSDs before they start coding; others are fine with back-of-the-napkin sketches along with a solid UI component library. Find out what they need, and provide just that — anything more than what they need will not get looked at, and that’s when tempers can really flare up.

Bringing such diverse worlds together is hard work. But, in “So Happy Together: Designers and Engineers,â€� Dave Gustafson warns what might happen if you don’t invest in this:

What’s the alternative to this kind of collaboration? Keeping design and engineering separate, where the pass-off from one to the other is aptly called “throwing it over the wall.� Designers may enjoy an unhindered blue-sky design process, but they’ll likely be disappointed with what actually gets made. Without engineers in the design process, there are bound to be some unrealistic features in the concept — and without an understanding of the designers’ intentions and priorities, engineers are likely to compromise the design with changes to meet cost goals. Some money may have been saved on the engineering and manufacturing — but not enough to offset a product that misses the mark.

The Prioritization Process

When there is no clear development process, “prioritization� can end up being a complex algorithm consisting of the last email request sent, the job title of the requestor, and proximity to the development team. This is no way to build a product. One way to address the difficulties of prioritization is through the concept of a “product council.�

At a start-up, the entire company could make up this group — even if it’s a group of one. In large companies, the group should include the CEO and the VPs of each department, including marketing, product, engineering, support, etc. The name is not important — the purpose is. The product council would have weekly or by-weekly meetings with two goals:

1. Review the current product road map to assess whether the right priorities are being addressed.
2. Introduce new ideas (if any) that have come up during the week and discuss business cases and priorities.

This meeting would have several very positive outcomes:

• It would give the management team complete insight into what the product or design team is working on, and would allow for anyone to make a case for a change in priorities. This eliminates the vast majority of the politics you see at many organizations, and it frees up the teams to do what they do best: execute.
• No one in the company would be able to go straight to a designer or developer to sneak things onto the road map. The user, technical or business impact of every big idea must be demonstrated.
• It would prevent scope creep. Nothing would be put on the road map without something else moving out or down. This is absolutely critical to the development cycle.

From there, projects would move to small dedicated teams, which would have complete ownership of the design and implementation. The product council sets the priorities, not the details of implementation — those are up to the teams themselves. I’m always reminded of what Jocelyn K. Glei says in her excellent article “What Motivates Us to Do Great Work?â€�:

For creative thinkers, [there are] three key motivators: autonomy (self-directed work), mastery (getting better at stuff), and purpose (serving a greater vision). All three are intrinsic motivators.… In short, give your team members what they need to thrive, and then get out of the way.

In pursuit of collaboration, we run the risk of overshooting our target and gaining the false sense of security that “consensus� brings. Consensus too often results in mediocre products, because no one really gets what they want, so the result is a giant compromise. Marty Cagan says this very well in his article “Consensus vs. Collaboration�:

In consensus cultures people are rarely excited or supportive. Mostly because they are very frustrated at how slow things move, how risk-averse the company is, how hard it is to make a decision, and especially how unimpressive the products are.

So, even though everyone agreeing on something is great, having someone be responsible for the decisions in that particular project is infinitely more important. This person does not do all the work, but rather is the one who owns the product’s fate — its successes and failures.

In many organizations, this person is the product manager, but it doesn’t have to be. Whoever it is, the role should be clearly defined and well communicated to the rest of the organization. The role is not that of a dictator, but of a diplomat, working with UX, business functions and engineering to build products that are driven by user, business and technology needs.

Level 4: Communicate Better

Once the appropriate guidelines are in place and the teams are working effectively, it’s time to root out any other causes of mistrust that might still exist. And one of the best ways to build trust in an organization is to eradicate secrets.

I am huge believer in full transparency, and I see little need in keeping any relevant information about a project from anyone. (The prerequisite? Hire trustworthy employees!)

If plans, progress and problems are published for all to see, there is no need to hide anything and no need to play politics to get things done. Here are just some of the things that should be published on a public wiki for anyone to view and comment on (written from the perspective of a UX team):

• Roles and responsibilities of the product and UX teams.
• How road-map planning and the prioritization process work.
• How the product development process works, including (critically) where UX fits into even the smallest projects.
• The goals and success metrics for every product line.

Publish everywhere, invite anyone. The tools at our disposal make this so easy, from Dropbox and Google Docs to ConceptShare and Campfire. There is no excuse for keeping things to ourselves.

Level 5: Prove That It Works

When the groundwork is laid for silos to start crumbling down, one last piece of dynamite will blow it all up: it’s time to start proving that it works. People will believe you for only so long if you say, “Trust me, this is the right thing to do!â€� At some point you have to show them the money.

A common theme throughout this series has been that better collaboration results in better software. The only way to cement these changes into the organizational culture is to show that you’re actually shipping a better product because of it.

Here’s what I do to demonstrate the business value of a collaborative development process that includes a tightly integrated UX cycle:

1. Share case studies from other companies or projects that clearly show the business benefits of working this way. Showing that it’s been successful elsewhere should buy enough time and resources for the team to put in place its plans to follow a proper collaborative design and development process in one or more of its projects.
2. Start on a project where changes can be measured by an improvement in one of the three A’s of revenue generation:
   • Acquisition
     Getting new users to sign up for your product.
   • Activation
     Getting those new users to make their first purchase.
   • Activity
     Getting those first-time purchasers to come back for more.
3. Benchmark well before the start of the project, and set clear goals to measure the success of the project.
4. Follow through on the commitment to collaboration, and measure your results. See “How to Measure the Effectiveness of Web Designs� for ideas on which measurement tools to use.
5. Publish your metrics widely so that everyone in the organization can see the results. And don’t hide the failures. There will be failures — the trick is to own those mistakes, learn from them and get better.

Summary (aka “Whose Job Is It, Anyway?�)

So, whose job is it to break down organizational silos and build a collaborative development process?

Guess what? It’s your job. Whether you’re a designer, developer or manager, this isn’t something that someone else will get around to — if it was, then it would have happened already. Building collaboration is best done through a groundswell in the organization, led by the makers, the people who build the actual product. It might be difficult, but I hope there are enough case studies and examples in this series to help you get started on this journey of organizational change.

Collaboration only works if everyone in the organization is open about their processes and workflows, without fear of being judged unfairly. Arguments over what’s right and how to do things differently will happen. And they should — it’s the only way to get better at what we do.

Building collaborative environments is not easy, because change management is not easy. But the positive outcomes of doing this far outweigh the pain of making it happen. You’ll end up with happy, creative teams that feel a sense of ownership over what they’re building and a sense of pride in its quality.

I often remind my team that we are judged on the products we ship, not on the number of times we ask for help along the way. So, what possible reason could there be not to collaborate and create a better product — because it will make us all look better in the end anyway? (Hint: there isn’t one.)

Go. Make it happen.

(al)

---

© Rian van der Merwe for Smashing Magazine, 2011.

Many websites these days have some form of welcome area on their homepage. Welcome pages generally act as an introduction for new visitors, explain the website and often prompt an action on the part of the user.

Website welcome pages are typically more prevalent at personal websites, portfolios, and traditional businesses. They are less popular on news websites (where the headline story acts as the introduction). Of course, welcome areas aren’t considered necessary on sites with a clear purpose and established audience – there would be no point having a welcome page at CNN.com, as their user base most likely already knows who they are.

Often a slogan can suffice to help establish what a site offers. If you are pushed for space, or consider a full welcome area to be obsolete then a brief tag-line explaining what your site does is a handy alternative.

Below is an outline of common traits that are seen throughout popular welcome pages:

• Large, bold typography. Welcome messages are easy to read and have more impact when the type is large, clear and legible. This means good contrast against it’s background, and often bold font choice.
• Plenty of color. In researching this article a definite trend of colorful welcome areas was noticeable. The reason behind this makes sense – the eye is drawn to color.
• Artistic/creative typography and graphics. Often the wider content will have more standard web-safe typography, but the welcome area will have elaborate fonts, complex graphics, lighting effects and imagery. This means that rather than just blend in as another area of content, the welcome area will act as a graphical composition in it’s own right.
• A simple and concise message. You can save the paragraphs of text for elsewhere on your website, a successful website should be summing up your website as concisely as possible, just a few sentences max.
• Informative photos. If a picture speaks a thousand words, then it makes sense to include photos in your welcome area. For a personal site a photo can add a nice human touch, or for a more corporate site a great product shot can speak wonders about the quality of the website/company.

Inspiring Welcome Areas:

To better illustrate these traits, here are some analyses of a range of successful website welcome pages below:

Syropia Labs
Syropia Labs use some really elegant typography in a retro style to create an engaging welcome area. The font choices are reminiscent of a 50s American diner, and the retro patterns and shapes used accentuate this theme. The text concisely and clearly summarizes the site’s content.

Olive and Twist
This welcome message uses bold typography to catch the users eye. The concise line ‘Creative design studio’ perfectly summarizes the site. The fact that this text is the lightest text on the page set against a predominantly dark background means that it really stands out.

Adrenalin Media
The bright, colorful imagery of this welcome area immediately draws the eye. This welcome message is part of an interactive slideshow area, constructed using jquery. The capitalized text is bold, with a subtle drop shadow to contrast it further against the bright blue background.

Luca Vercellio
Luca Vercellio uses a very minimal homepage design, where the welcome message comprises most of the page. The welcome area is relatively subtle, with a soft light effect, and white on light blue color palette. The typography varies quite a lot, but is all light and clear, fitting with the modern, clean website design. Nothing too elaborate here, just a nice simple message, with a personal touch ‘Hello I’m Luca’.

Somersby Cider
Much more a visual spectacle, than a typography welcome area. There is the basic welcome slogan ‘stay open-minded’ but the really impression is created by the beautiful photo manipulation, which features the product in an attractive way. The fantasy world presented creates a magical mood for new visitors, and a sense of intrigue and wonder that should encourage them to check out more of the site.

Sentel
A clean and minimal welcome area with a limited color palette. The key words ‘designing’ and ‘promoting’ which describe company’s key services are highlighted in blue in order to make them more prominent. The welcome message uses a light font, with a solid colored background to help contrast it against the main pixelated website background.

BeMobile
Be Mobile is a really bold website, combining black, yellow and white for a colorscheme with plenty of impact. This welcome message uses creative copy, starting each line with ‘Be’, leading up to their company name ‘Be Mobile’ at the bottom line. In addition to this is a bold, black call to action button, ensuring that the users eye is drawn first down the page, then into taking action.

Aleks Faure
Another example of great copy. This copy introduces the designer, establishes what he does, and adds a sentiment about his quality and work ethic. The welcome area is simple but effective, and uses @font-face to integrate a creative font.

Narax
A really engaging welcome area, with a moving animation of an origami arc to fit with the slogan. The simple slogan ‘Your ark to the web’ is a little ambiguous, and doesn’t really describe what the site does. However, it does create intrigue. It’s actually the under slogan which explains the services offered. The pastel colors and cross-hatched paper area give a feeling of creativity, which fits well with the design theme of the company.

Syropia
This welcome area uses a retro look to help draw in users. The typography is varied, but comes together well as part of a great piece of imagery to headline the site. The copy has a nice personal touch as the webmaster states ‘I’m here to help you get there’. Color is uses sparingly, but red is used to emphasize key words.

Giebe Graphics
Another great example of copy defining the welcome area. The welcome message is very personal, and the grayscale color palette is broken by splashes of blue on key words. The opening line in speech marks (“nice to meet you!”) puts across a lot of energy and really helps connect with the visitor. The font is large and bold, with a subtle indented design to help it stand out against the page background.

Tiny Verse
In my opinion this welcome area has too much text after the initial headline, and it’s not all that legible against the background. However, what really makes this welcome area successful is the exciting photo manipulation in the right. The welcome area background is also really eye catching, and the space age cloud theme is sure to entice people.

Noutes
A bold and bright welcome area that acts as a header to the rest of the website. This welcome area utilizes a large icon for imagery, which provides a shiny, professional touch. The typography is fairly basic, yet instantly and concisely sums up the aims of the website. There is also a large, prominent Facebook Connect call to action.

Touch Tech
Touch Tech uses a great memorable illustration, with relevant imagery of clouds and mobile devices. The typography is large, professional, yet with a friendly aspect to it, using rounded lettering. The copy is very basic, yet instantly establishes who the company are and what they do (‘mobile and cloud developers’).

Gabriel Aloysius
A wonderfully simple welcome area, with some hugely creative typography. Rather than use plain type, the letters act as a mask, letting imagery show through them. This imagery is constantly changing as part of a montage to showcase the photographers work, creating a welcome area with a double function. The way that the letter shapes contain her work acts almost like a window, where you’re wanting to see in.

Bear Grylls Live on Stage
A totally immersive welcome area experience. The jungle backdrop creates an enormous sense of depth, as does the huge 3D typography and foreground photographs. This welcome area perfectly captures the feeling intended by his live shows – that you as viewer are part of the action.

Goodsie
A simple but effective welcome area. The welcome beings with their mission station ‘Online retail should be easy’, which is effective as rather than trying to directly sell themselves, their selling point becomes their integrity and company values. The large, elegant white typography contrasts well against the dark blue background, and the bright call to action button attracts plenty of attention. Notice how the blue background also integrates silhouettes of retail products, creating a subtle but relevant backdrop for the welcome message.

Epic Fleet
A bold, striking welcome area with some nice copy. The emboldened text ‘you can afford’ underlines the central message of this company, which is value. The concise message also instantly states what they provide (‘web design’). Underneath this some examples of their work are attractively displayed in a fan pattern, in order to create additional visual intrigue.

We Are Pandr
A stylish welcome area in an illustrative style. The welcome copy is highlighted by using a simple black backdrop featuring white typography. The main green background uses simplistic illustrations and patterns so as not to detract from the central message. The colors are bright, clean but limited, so the eye cannot help be drawn to the welcome headline.

Bear Hat Studios
A classic example of a welcome area using HUGE typography. The simple textured background ensures that the large text is the central focus, particularly as it takes up 80% of the homepage. There are no fancy words here, just simple copy that clearly states what this company provides. The typography is made more interesting through subtle gradient overlays and faint drop shadows. All of these design features serve to emphasize the welcome text.

Made by Vadim
A creative welcome area with a stylized, abstract illustration at it’s center. The welcome message itself serves to introduce the designer and clarify exactly what he does. The personal ‘Hello’ message is emphasized through the use of scripted typography and large text. The abstract illustration of the designer not only provides a personal insight into his world, but helps to show off his design skills.

Putra Roeung
Another welcome area that concisely states what the website owner does. The subtle background design of this welcome area really works well. If you look closely you’ll see examples of their work and design processes behind the main text. The logo badge is a nice grungy touch to add creativity to the design, and the two call to action buttons are accentuated by sketchy arrows pointing to click them.

Spout Creative
A quaint, easy-on-the-eyes welcome area, this site utilizes pastel colors and soft illustrations to provide a friendly welcome for people. The typography is well organized and uses reasonably informal fonts to add to the casual mood of the website. The illustration of the girl using the megaphone gives the text more of an auditory aspect, as she is clearly announcing the welcome message.

CMYK08
A great example of a highly personal welcome area. This designer combines a personal photo, an informal greeting (‘hello folks!’) and some nice grungy/sketchy touches to reflect his design style and personality. He has manipulated his own photo to fit with the limited color palette of the website, where blue, light gray and black combine to result in a stylish welcome page. The tagline by his photo ‘I think I need a haircut’ is another insight into his humor and presumably approach to design.

Chapter Three
A reasonably formal welcome area, this design uses bright teal colored lettering for the main welcome headline, which contrasts effectively against the dark gray background. Key words are highlighted in orange, and their location (San Francisco) is integrated very creatively into the shape of the Drupal logo (which of course is relevant to the services they provide).

Masswerks
A very simple but attractive welcome area. The copy is a friendly greeting, followed by a description of the firm’s services. The bold black text contrasts well against the bright orange backdrop, and is emphasized further by use of a thin white drop shadow. The fact that the logo and welcome message are on a single line gives a unified sense to the design, and visually connects the company’s brand with the sentiments of their welcome message.

Alan Power
This welcome area avoids being overly busy, but creating a great visual hierarchy, drawing the eye diagonally down the header. The bold, large typography of the welcome area is really eye catching and the splashes of red work nicely. The simple gray background helps foreground the welcome message, which is emphasized by the examples of the company’s work to the left. Ultimately the eye is drawn down the header to the nicely textured call to action button, encouraging client contact.

New Concept
This welcome area uses photography to enhance the message within the copy. ‘Beautiful & Elegant’ describes their designs, but is also depicted by the beautiful, elegant butterfly to the right of the welcome text. When you hover over the butterfly image a magnified circle pops up, providing an interactive element to the welcome area, which helps maintain people’s interest.

Uproar PR
A great example of effective typography in a welcome area. Not only is the welcome type large and eye catching, but it impacts upon the surrounding environment. In this case we see the word ‘NOISE’ actually cracking the surface that it rests on, which creates a much more real environment for visitors. The lens flare effect and metallic sheen also draw the eye. The imperative nature of the copy ‘make some noise!’ is a much more aggressive message than other examples in this post, yet fits with the cut-throat nature of the PR industry.

Joe Guarino
Another designer who uses an informal welcome approach for potential clients. Rather than hide behind a false corporate mask, Joe presents himself honestly and openly, through a fun self portrait illustration and some funky typography. The informal copy ‘Hi, man!’ establishes a friendly vibe for potential clients and helps draw them further into his site.

Kendra Schaefer
This site uses photography as the principle feature of the welcome area. The typography is reasonably large, but isn’t all that legible, and doesn’t provide a huge amount of information. It’s more there for a humorous, abstract message. The photography is the real gem of this welcome area, as it’s dark, moody and emotion, and captures a lot of attention. As a visitor we want to know more about the figure depicted, and as a result browse around the rest of the page for clues.

Shout Digital
A bright, colorful welcome area with a crazy Flash animation. The actual text of the welcome area comes below this animated area, but the quality of illustration and animation is so superb that the site has already won you over.

Convax
This welcome area integrates examples of the company’s work really creatively, by positioning them as a billboard in amongst a sketched out cityscape. The call to action button ‘get in touch’ is creatively integrated into the background, sitting within a sketched cloud shape.

Amit Tishler
A welcome area that’s highly appropriate for an animated, showcasing an awesome vector backdrop for the page. The welcome area includes a Youtube video, which showcasing the animator’s work better than a static image could.

Jeremy Man
This welcome area has an awesome western theme that fits well with the overall site. The welcome text actually isn’t an image, and uses @font-face and some cool css effects to style it. The indented illustrations and background textures create an authentic cowboy aesthetic, as does the copy (‘Heckuva’ Frontier Wranglin’).

NorthEast Creative
North East Creative use some great background lighting effects to foreground their concise welcome message. The colors of this area compliment each other well, and the bright yellow text stands out against the deep purple background. There is a central fan design displaying examples of their work, which works to create depth and a visual attraction for visitors.

Web Munky
Web Munky use their cheeky mascot and colorful logo at the centerpiece for their welcome area. However, the tagline ‘we craft online experiences’ provides an informative sub text for the area. The bright, vibrant colors draw the users eye, and the visual hierarchy effectively prompts you to scroll down the page and find out more about their services.

Media Germ
Another great example of text masking. This media company lets their work show through the shape of the welcome area lettering. The typography is really bright and eye catching, although the legibility is slightly hindered by the busy fill. The length of each line of text means that the eye is naturally drawn down the block of text to the smaller call to action button.

Raven Tools
Raven Tools use a relatively reserved color palette for their welcome area. However, the great background lighting and creative typography adds a lot of impact. The copy is concise and immediately lets users know what the company does: ‘A powerful internet marketing platform for agencies and professionals’. The screenshots beneath this help showcase how the platform works, followed by a bright call-to-action button.

Crssrd
A really artistic welcome area that shows off the artist’s talents. The grungy illustration fits in perfectly with the surrounding textured website and typography. Even without analyzing the copy of this welcome page it had to be included as an example of how a great central design can make a welcome area memorable. Remember – a picture can often be worth 1000 words, and in this example no text is required to showcase the designers skill.

(rb)

Do you consistently work to stay engaged, or do you get comfortable with clients? With new projects, it's easy to make the extra effort. The longer you work together, the easier it becomes to feel satisfied with the status quo, while giving your best energy to the shiny new client. Rather than pretend this won’t happen, prepare for it and create a strategy to combat it. Shane Pearlman shows us how.

Customers aren't shy about shouting their experiences—good and bad—to the world via Twitter and Facebook. When you see customer service as a cost center, you risk treating customers as a liability. Yet, customers are a valuable resource: their feedback is integral to shaping your product and building your brand. Customer service, by definition, is about serving people; it should be genuine, personalized, and compassionate—or, simply put, human.

PayPal is the most popular platform for receiving online payments today. The ease of opening a PayPal account and receiving payments compared to opening a merchant account with a traditional payment gateway is probably the number one reason for its popularity, with a close second being the comprehensive API that PayPal provides for its payment services.

Disclaimer: PayPal’s API is among the worst I’ve ever had to deal with. Inconsistencies, sometimes poor or conflicting documentation, unpredictable failures and account changes, and major differences between the live and sandbox versions all conspire to make the PayPal API quite a pain in the arse to work with. Over the years, I’ve taken my lumps from working quite a bit with the PayPal API, and I’ve published the results of my hard-learned lessons as a commercial PHP PayPal API component on the source-code marketplace Binpress.

In this post, I will break down some of the techniques and approaches to working with the PayPal API, in order to make integration and troubleshooting simpler and easier.

The Different Payment Options

PayPal offers a variety of payment options, which might be confusing at first:

• Express Checkout
  The premier PayPal service. Express Checkout allows you to receive payments without having a merchant account and without having to meet special requirements other than verifying your account (either via a bank account or a credit card). Previously, you could receive Express Checkout payments from PayPal users only, but PayPal has since added a credit-card option for non-PayPal users, making this service accessible to practically anyone with a major credit card. Note that the Express Checkout process occurs on PayPal’s platform and thus can never be fully integrated in your website’s experience.
• Direct Payment
  The Direct Payment method allows you to receive credit-card payments directly through an API call. This enables you to host the payment process on your website in full, which might make for a more complete shopping experience for your customers. The Direct Payment method has several variations that enable you to authorize a payment and complete it at a later date: the appropriately named Authorization and Capture methods. These variations are a part of the Website Payments Pro API, which is available only to US, Canadian and UK accounts.
• Recurring Payments
  This allows you to set up a recurring transaction (i.e. a subscription payment).
• Mass Payments
  This allows you to transfer money to multiple accounts at once.
• Adaptive Payments
  Here is another API for sending funds to multiple recipients, with some differences from the Mass Payments API. (Did I mention that the PayPal API is confusing and a bit redundant?)

This list is not comprehensive, but it covers the main payment options (see the API documentation for more).

Making API Requests

PayPal supports two main formats over HTTP: NVP and SOAP. NVP is short for Name-Value Pair, and SOAP stands for Simple Object Access Protocol. I will cover the NVP approach, which I prefer to SOAP’s relatively verbose and complex syntax.

Each of the API methods has different parameters, but they all share some basic parameters, which are used to identify the API account and sign the transaction. These include:

• USER
  Your PayPal API user name.
• PWD
  Your PayPal API password.
• VERSION
  The version number of the NVP API service, such as 74.0 (the most recent as of this writing).
• SIGNATURE
  Your PayPal API signature string. This parameter is optional if you use a certificate to authenticate.

The last required parameter is METHOD, which declares which API method we are calling.

Requests are made over HTTPS. We’ll use cURL to build our basic request, and then encapsulate the process in a class:

class Paypal {
   /**
    * Last error message(s)
    * @var array
    */
   protected $_errors = array();

   /**
    * API Credentials
    * Use the correct credentials for the environment in use (Live / Sandbox)
    * @var array
    */
   protected $_credentials = array(
      'USER' => 'seller_1297608781_biz_api1.lionite.com',
      'PWD' => '1297608792',
      'SIGNATURE' => 'A3g66.FS3NAf4mkHn3BDQdpo6JD.ACcPc4wMrInvUEqO3Uapovity47p',
   );

   /**
    * API endpoint
    * Live - https://api-3t.paypal.com/nvp
    * Sandbox - https://api-3t.sandbox.paypal.com/nvp
    * @var string
    */
   protected $_endPoint = 'https://api-3t.sandbox.paypal.com/nvp';

   /**
    * API Version
    * @var string
    */
   protected $_version = '74.0';

   /**
    * Make API request
    *
    * @param string $method string API method to request
    * @param array $params Additional request parameters
    * @return array / boolean Response array / boolean false on failure
    */
   public function request($method,$params = array()) {
      $this -> _errors = array();
      if( empty($method) ) { //Check if API method is not empty
         $this -> _errors = array('API method is missing');
         return false;
      }

      //Our request parameters
      $requestParams = array(
         'METHOD' => $method,
         'VERSION' => $this -> _version
      ) + $this -> _credentials;

      //Building our NVP string
      $request = http_build_query($requestParams + $params);

      //cURL settings
      $curlOptions = array (
         CURLOPT_URL => $this -> _endPoint,
         CURLOPT_VERBOSE => 1,
         CURLOPT_SSL_VERIFYPEER => true,
         CURLOPT_SSL_VERIFYHOST => 2,
         CURLOPT_CAINFO => dirname(__FILE__) . '/cacert.pem', //CA cert file
         CURLOPT_RETURNTRANSFER => 1,
         CURLOPT_POST => 1,
         CURLOPT_POSTFIELDS => $request
      );

      $ch = curl_init();
      curl_setopt_array($ch,$curlOptions);

      //Sending our request - $response will hold the API response
      $response = curl_exec($ch);

      //Checking for cURL errors
      if (curl_errno($ch)) {
         $this -> _errors = curl_error($ch);
         curl_close($ch);
         return false;
         //Handle errors
      } else  {
         curl_close($ch);
         $responseArray = array();
         parse_str($response,$responseArray); // Break the NVP string to an array
         return $responseArray;
      }
   }
}

Note that I use a CA certificate file for SSL certificate validation. You can obtain the file from the cURL website or any trusted source. Update the path to the certificate file according to where you’ve placed it.

The response returned will be in NVP format as well, and I reformat it into an array before returning it. A parameter named ACK signifies the status of the request: Success or SuccessWithWarning when the request succeeds, and Error or Warning when the request fails.

A request could fail for many reasons, and there are different reasons for each API method, which are covered in detail in the manual. We’ll go over some further down in this article and look at ways to handle them. Keep in mind that the parameter values are case-sensitive, so code against them accordingly.

Express Checkout

One of the most popular APIs is the Express Checkout API, which enables you to receive payments without opening a Website Payments Pro account (which is available only to verified US accounts) or hosting the actual transaction yourself (which requires additional security).

The Express Checkout process works as follows:

1. We request a checkout token from PayPal using the transaction details;
2. If successful, we redirect the user to the PayPal endpoint using the received token;
3. The user completes or cancels the payment on the PayPal platform and is redirected back to our website;
4. We complete the payment either when the user is redirected back or via an Instant Payment Notification (IPN).

1. Getting the Checkout Token: SetExpressCheckout

We initiate the Express Checkout process by passing the order details to the PayPal API, and we receive a token string that identifies it. This token would be used in the next step to redirect to PayPal.

Here are the required parameters:

• METHOD
  This is the API method that we’re using (i.e. SetExpressCheckout).
• RETURNURL
  The URL that the user will be redirected to after the payment process is completed.
• CANCELURL
  The URL that the user will be redirected to after having cancelled the payment process.
• PAYMENTREQUEST_0_AMT
  The transaction’s total amount. This must have two decimal places, with the decimal separator being a period (.). The optional thousands separator must be a comma (,).
• PAYMENTREQUEST_0_ITEMAMT
  The total cost of the items in the order, excluding shipping, taxes and other costs. If there are no extra costs, then it should be the same value as PAYMENTREQUEST_0_AMT.

We can pass additional parameters to add more information about the order, some of which have default values:

• PAYMENTREQUEST_0_CURRENCYCODE
  The payment’s currency, as a three-letter code. The default is USD.
• PAYMENTREQUEST_0_SHIPPINGAMT
  The total shipping costs for this order.
• PAYMENTREQUEST_0_TAXAMT
  The total tax amount for this order. This is required if per-item tax is specified (see below).
• PAYMENTREQUEST_0_DESC
  The order’s description.

We can also add details about individual items in the order:

• L_PAYMENTREQUEST_0_NAMEm
  The item’s name.
• L_PAYMENTREQUEST_0_DESCm
  The item’s description.
• L_PAYMENTREQUEST_0_AMTm
  The item’s cost.
• L_PAYMENTREQUEST_0_QTYm
  The quantity of an item.

The variable index m identifies the item. (Use the same variable for all details of the same item.)

There are many other optional parameters, which can be found in the API documentation.

We’ll use the function that we wrote above to build the SetExpressCheckout request:

//Our request parameters
$requestParams = array(
   'RETURNURL' => 'http://www.yourdomain.com/payment/success',
   'CANCELURL' => 'http://www.yourdomain.com/payment/cancelled'
);

$orderParams = array(
   'PAYMENTREQUEST_0_AMT' => '500',
   'PAYMENTREQUEST_0_SHIPPINGAMT' => '4',
   'PAYMENTREQUEST_0_CURRENCYCODE' => 'GBP',
   'PAYMENTREQUEST_0_ITEMAMT' => '496'
);

$item = array(
   'L_PAYMENTREQUEST_0_NAME0' => 'iPhone',
   'L_PAYMENTREQUEST_0_DESC0' => 'White iPhone, 16GB',
   'L_PAYMENTREQUEST_0_AMT0' => '496',
   'L_PAYMENTREQUEST_0_QTY0' => '1'
);

$paypal = new Paypal();
$response = $paypal -> request('SetExpressCheckout',$requestParams + $orderParams + $item);

2. Redirecting to PayPal Using the Checkout Express Token

If the request is successful, we’ll receive a checkout token in the TOKEN parameter of the response.

if(is_array($response) && $response['ACK'] == 'Success') { //Request successful
      $token = $response['TOKEN'];
      header( 'Location: https://www.paypal.com/webscr?cmd=_express-checkout&token=' . urlencode($token) );
}

The user now goes through the purchase process on PayPal’s website. When they confirm or cancel it, they will return to one of the URLs that we’ve specified in the request.

3. Completing the Transaction

Assuming the user confirms the transaction, they will be redirected to our website by PayPal. At this point, we should use two relevant API methods: DoExpressCheckoutPayment will complete the transaction, but before that we might want to get additional information on the buyer using GetExpressCheckoutDetails.

PayPal will redirect the user back from the purchase with the checkout token, which we will use to call those methods. The token will be available in the URL query parameters via the token parameter. We will check for its existence in the confirmation URL and then send our API requests if we find it.

The GetExpressCheckoutDetails method requires only the checkout token. DoExpressCheckoutPayment requires a couple of additional parameters:

• PAYMENTREQUEST_0_PAYMENTACTION
  This is the payment action. It should be set to Sale unless we’ve specified a different action in the SetExpressCheckout method (possible values include Authorization and Capture).
• PAYERID
  This is the unique identification for the PayPal account. This, too, is returned in the URL query parameters (in the PayerID parameter) and can also be retrieved from the details returned by GetExpressCheckoutDetails.

if( isset($_GET['token']) && !empty($_GET['token']) ) { // Token parameter exists
   // Get checkout details, including buyer information.
   // We can save it for future reference or cross-check with the data we have
   $paypal = new Paypal();
   $checkoutDetails = $paypal -> request('GetExpressCheckoutDetails', array('TOKEN' => $_GET['token']));

   // Complete the checkout transaction
   $requestParams = array(
      'PAYMENTREQUEST_0_PAYMENTACTION' => 'Sale',
      'PAYERID' => $_GET['PayerID']
   );

   $response = $paypal -> request('DoExpressCheckoutPayment',$requestParams);
   if( is_array($response) && $response['ACK'] == 'Success') { // Payment successful
      // We'll fetch the transaction ID for internal bookkeeping
      $transactionId = $response['PAYMENTINFO_0_TRANSACTIONID'];
   }
}

Direct Payment

The Direct Payment API allows you to receive payments directly on your website or application, giving you complete control over the checkout process. PayPal tends to push users to register and use a PayPal account, which is understandable, but this conflicts somewhat with our interest to make the payment process as simple and clear as possible for our customers. For this reason, full control over the checkout process is preferred and gives us more options to optimize sales and generate more sales.

The process is a bit simpler than that of Express Checkout, because the entire interaction occurs on our website, and we need to perform just one API call to process a normal payment: DoDirectPayment.

A couple of more API requests are required if you want to perform a transaction that is billed at a later date (for example, when you ship the product or confirm availability). These would be the Authorization & Capture API methods, which I will not cover in this post, but be aware that this option exists.

DirectPayment Parameters

DirectPayment requires different parameters than Express Checkout, as to be expected. While the transaction details parameters are similar (with different key names, to make it more interesting), the method also requires credit-card and address information.

DirectPayment’s basic parameters:

• METHOD
  This is DoDirectPayment.
• IPADDRESS
  This is the IP address of the payer. In PHP, we can retrieve it using the superglobal $_SERVER['REMOTE_ADDR']. You’ll have to do a bit more work to get the IP when dealing with set-ups that have a proxy between the PHP process and the outside network (such as nginx).
• PAYMENTACTION
  This is the type of action that we want to perform. A value of Sale indicates an immediate transaction. A value of Authorization indicates that this transaction will not be performed immediately, but rather will be captured later using the Authorization & Capture API mentioned earlier.

Credit-card details:

• CREDITCARDTYPE
  The credit-card type (Visa, MasterCard, etc.). See the API documentation for the full list.
• ACCT
  The credit-card number. (Don’t you love these abbreviated key names?) This must conform to the particular format of the card’s type.
• EXPDATE
  The expiration date, in MMYYYY format (i.e. a two-digit month and a four-digit year, as one string).
• CVV2
  The “card verification value,� or security code, as it’s sometimes known.

Payer information and address parameters:

• FIRSTNAME, LASTNAME
  The payer’s first name and last name, respectively (in separate fields). You can also provide an email address in an EMAIL parameter, but it’s not required.
• CITY, STATE, COUNTRYCODE, ZIP
  The city, state, country code (as a two-letter code) and zip code parts of the address, all required.
• STREET, STREET2
  Two lines for the address (only the first is required).

This address will be used in the address verification system (AVS). You’ll receive a specific error code if a transaction has failed due to an address verification failure.

The payment details parameters are the same as the ones for Express Checkout, but with slightly different names (AMT, ITEMAMT, CURRENCYCODE, SHIPPINGAMT, TAXAMT and DESC) and without the PAYMENTREQUEST_0_ prefix. Refer to the previous section or the API documentation for specific details on those.

Similarly, the item details parameters are similar to those of Express Checkout. These include L_NAMEm, L_DESCm, L_AMTm and L_QTYm, giving you granular control of item details in the order summary. The m integer variable is used to account for multiple items (replace with 0, 1 and so on for numbered items in the order). See the API documentation for a comprehensive list of item details.

Performing the Transaction

Sending the request using our function is very similar to GetExpressCheckoutToken. We pass all of the parameters into the request function as before, with the method set to DoDirectPayment.

$requestParams = array(
   'IPADDRESS' => $_SERVER['REMOTE_ADDR'],
   'PAYMENTACTION' => 'Sale'
);

$creditCardDetails = array(
   'CREDITCARDTYPE' => 'Visa',
   'ACCT' => '4929802607281663',
   'EXPDATE' => '062012',
   'CVV2' => '984'
);

$payerDetails = array(
   'FIRSTNAME' => 'John',
   'LASTNAME' => 'Doe',
   'COUNTRYCODE' => 'US',
   'STATE' => 'NY',
   'CITY' => 'New York',
   'STREET' => '14 Argyle Rd.',
   'ZIP' => '10010'
);

$orderParams = array(
   'AMT' => '500',
   'ITEMAMT' => '496',
   'SHIPPINGAMT' => '4',
   'CURRENCYCODE' => 'GBP'
);

$item = array(
   'L_NAME0' => 'iPhone',
   'L_DESC0' => 'White iPhone, 16GB',
   'L_AMT0' => '496',
   'L_QTY0' => '1'
);

$paypal = new Paypal();
$response = $paypal -> request('DoDirectPayment',
   $requestParams + $creditCardDetails + $payerDetails + $orderParams + $item
);

if( is_array($response) && $response['ACK'] == 'Success') { // Payment successful
   // We'll fetch the transaction ID for internal bookkeeping
   $transactionId = $response['TRANSACTIONID'];
}

There are plenty of parameters, but all relatively simple.

Error Handling

In a perfect world, this section would not exist. In reality, you will be referring to it quite a lot. PayPal can fail a transaction for a multitude of reasons, not all of which you can control.

The $response variable we returned from our paypalApiRequest() function could contain a different value than Success for the ACK parameter. That value could be:

• Success
  Indicates a successful operation.
• SuccessWithWarning
  Indicates a successful operation, and that messages were returned in the response that you should examine.
• Failure
  Indicates a failed operation, and that the response contains one or more error messages explaining the failure.
• FailureWithWarning
  Indicates a failed operation, and that messages were returned in the response that you should examine.

This gives us two success statuses and two failure statuses. The mock code above tests for the Success value only, but we could change it to check for SuccessWithWarning as well; and keep in mind that we need to find out what the warning is. A common scenario is that a Direct Payment charge will have been performed successfully, but the credit-card company responds that the transaction has failed, for whatever reason.

Errors from PayPal are returned in four parameters in the response:

• L_ERRORCODE0
  A numeric error code, which can referenced against PayPal’s error code list (there are quite a few).
• L_SHORTMESSAGE0
  A short error message describing the problem.
• L_LONGMESSAGE0
  A longer error message describing the problem.
• L_SEVERITYCODE0
  The severity code. (I couldn’t find any useful documentation on this, and it doesn’t really matter, so let’s put it aside.)

The 0 part of these parameters is an incrementing integer for multiple error message (1, 2, etc.).

Here are some common errors you’ll run into:

• 10002
  Authentication or authorization failed. This usually indicates invalid API credentials, or credentials that do not match the type of environment you are working in (such as a live or sandbox environment).
• 81***
  Missing parameter. There are quite a few of these, all starting with 81. Each refers to a specific required parameter that is missing from the request.
• 104**
  Invalid argument. This indicates that one of the supplied parameters has an invalid value. Each argument has specific errors, all starting with 104. A common one is 10413, which means that the total cost of the cart items does not match the order’s amount (i.e. the total amount parameter, AMT, does not equal the items’ total plus shipping, handling, taxes and other charges).

How Do We Handle These Errors in Practice?

PayPal error messages vary and could contain private information that you do not want your users to see (such as an invalid merchant configuration). That being the case, showing PayPal error messages directly to users is not advisable, even though some of them might be useful.

In most cases, I would do the following:

1. Set up a white-list array of errors that can be shown safely (such as a missing credit-card number and expiration date);
2. Check the response code against that array;
3. If the error message is not white-listed, then display a generic message, such as “An error has occurred while processing your payment. Please try again in a few minutes, or contact us if this is a recurring issue.�

If an error falls outside of the white-listed array, I will also log it to a file on the server and send an email to the administrator, with the full details so that someone is up to speed on payment failures. In fact, logging PayPal requests and responses is good practice regardless of errors, so that you can monitor and troubleshoot payment failures (I provide this option in the commercial component that I mentioned at the beginning of this article).

Ready To Get Started With The PayPal API?

In this post, I’ve covered two of the most widely used API methods, as well as error handling with the PayPal API. This should be enough for you to get started using the most popular payment platform online.

The PayPal API has many more methods and processes, more than can be covered in any one post. Once you get up to speed on the basic methods, learning the others should be relatively straightforward (even if somewhat exhausting). I hope this guide has given you a good head start on using the API. If you have questions or comments, I would love to hear from you in the comments!

Front cover: Image source

(al)

---

© Eran Galperin for Smashing Magazine, 2011.