In the past two weeks alone, I’ve needed to work out how four entirely different third-party payment solutions integrate and end up looking in apps. The types of integrations vary between surface-level hosted web pages all the way through to using deeply-integrated APIs. As a result, each and every solution looks completely different in implementation. Each time these integrations come into play, I have to scour my way through (often not very well constructed) development documentation; find out which elements of the solution are actually required; work out what restrictions there are on how each element looks and build them into a flow for a completed design. This happens all the time – often needing developers to come in and help – and the time spent can easily be avoided.
Let’s take one of the world’s most renowned pieces of development documentation out there to start: Stripe. These docs are built perfectly to teach developers how to use their APIs. For this purpose it works like a charm. Every developer I’ve spoken to about using Stripe has found it really easy and consistent. Product designers on the other hand are given varying types of assistance. This goes from really useful ‘what you’re building’ sections showing exactly how things look; to images showing some of the available customisation; to nothing at all in some areas. The solution to this issue is the introduction of a little non-dev documentation from those providing the integrations in the first instance.
The ideal process
The first thing any designer or product manager needs to see when looking through integration docs is a feature summary; a sample call and response; and – preferably in as compact an explanation as possible – all the variables you can throw into the mix and what they’re for. A perfect example of this part is Visa’s Cybersource platform. (https://developer.cybersource.com/api-reference-assets/index.html#payments) Right from the get-go, you can see what their API does; play with calls and responses in a sandbox environment; and see all the cool stuff you can do with it. For working out which forms need to go where or looking for suitability, this is perfect. It doesn’t require a great depth of coding knowledge to get a good idea for what can be done.
Next up is style limitations. These come in a variety of formats, be it a set of exposed CSS styles you can alter; some loose guidance on the kinds of UI permitted by the third party; a collaborative vetting process; complete freedom to do whatever you wish; or absolutely nothing at all you can change. The best of course is being able to do whatever you like, but this is rarely the case. The difference between these processes can be a little blurry from the outside, but it’s usually difficult to work out what the deal is from the onset anyway. Take Stripe’s example, as I’ve mentioned before, the design guidance attached to each part of their API is completely different. Provided these limitations are clear, the typical client-side design process can begin. You’ll soon see a well-crafted experience come out of the works, ready to go into development.
The importance of design
With design slowly becoming a key element in building digital products, its relative importance over other areas of product development has only increased with time. Startups are huge fans of applying design thinking principles to their latest stuffed-animal cannon, simply because it makes it better. Creating a great experience for the end customer is now core to nearly all product teams, and design plays a huge role in this. If the checkout process in a product doesn’t feel as smooth as possible to users because payment provider A doesn’t allow custom styling, come launch, conversions drop, and ultimately everybody loses out. As a result, product teams are more often than not looking for design when assessing the suitability of these third-party integrations in the first instance.
If companies producing integrations consider design early on when building documentation, things ultimately become easier for everyone. Developers can see what they’re making; designers can see what they’re able to do; and product managers can more easily assess for suitability (now with design in mind). If the end client asks how feature B works with integration C, there are far fewer misunderstandings. This simply because if there is documentation available for non-developers, those non-developers can understand it without having to worry they’ve missed something.
Writing complete development documentation is a mammoth task for any organisation to undertake. I can completely see why this isn’t typically on the radar. But the extra care taken for those who stand before developers might even result in more sales for these organisations. This simply because the people selecting their services can see immediately that it will work for them. No more having to faff about for an hour to find out if the one feature they’re looking for is available.