What I’ve learned in designing for developers, the discovery phase
Earlier this month we wrote about our end-to-end process in recreating our developer portal.
A number of people have asked us to elaborate on lessons learned from our user research when designing the developer portal and how research directly impacted our solution.
In reflection, I think there are three parts to this question:
1. What did we learn during our discovery phase and how did it apply to our approach?
2. What was changed when we validated our concepts?
3. How will we continue to build on what we have learned?
Honestly, that is a lot of ground to cover. Let’s tackle question #1 first: explaining our findings from the ‘discovery phase’ and how this was applied to our approach to building the product.
Why dogfooding is not enough
Dogfooding is awesome. Nothing motivates you to improve an experience than personally being affected by the impact of its flaws. However, if you’ve been at your company for a while, chances are you aren’t looking at things with fresh eyes anymore.
Bringing in outside developers who have little to no experience with Dwolla or our API was key. It enabled us to separate our internal knowledge and hypothesis from the real world impact of first time users. Exploratory research helps develop empathy, prioritize known issues, uncover issues you didn’t previously see and generate new ideas.
The biggest take-away from upfront exploratory research was defining task driven personas, guiding our information architecture and our design principles.
Understanding motivation
Traditionally, you might think that there is an overarching decision making evaluating product fit and looking at product pages, and a separate developer leveraging documentation to get something done. We found it isn’t so cut and dry. Decision makers, product managers and developers are all interested in the what and the how of an API company. So, we decided to develop task orientated personas to inform our process.
Here is a quick overview of the personas we defined:
Each of these roles — searcher, implementor, maintainer, hacker — will have varying degrees of experience developing products, and any given individual may play multiple roles at any time.
Thinking through these roles and their motivations directly fed into how we organized the information on the portal. We used what was discovered in the research phase to map out our plan and portal.
Tactical vs. Topical Content
Our previous developer portal was very topic driven. For example, we had one document for oAuth and another for batch payments. The downside was that in order to get anything done — you needed to read multiple documents. Time and again we observed people opening information in new tabs to keep track of where they had come from only to be swamped in a sea of tabs.
This simple observation led to very powerful design considerations.
We have launched with three main sections on the site: guides, resources, and API docs.
Our guides are our comprehensive how-tos that focus on our core use cases. They are designed to support the implementor and seeker quickly and easily get up and running.
Resources allow people to dive deeper into a topic, such as the options available for customer verification. This section is ideal for implementors or hackers, but is valuable for any of the four given personas.
API docs, of course, are where you go specifically to reference every parameter and detail of each endpoint — an important tool for extending on what you’ve achieved in the guides and useful for maintainers as well.
Skim, read, skim… skim.
Developer portals should make it easier to get the job done. Lets face it, this is work. Whatever you can do to make it easier to get something done is greatly appreciated by the dev community. There were a number of key objectives we wanted to achieve when creating our content.
Be comprehensive, but keep it simple.
For our guides, we created a step by step experience which provides an overview of how the product works, the process and context of the task ahead. Our steps also broke our guides into manageable chunks simplifying the end-to-end experience of the task.
Wherever possible, let the code do the talking. Reduce the words.
When it came to the content, we frequently observed developers reading the code first on any given document. Supporting content was predominately read if they had a question.
Avoid hyperlinking as a courtesy and only use when it is important.
Lastly, remember all that tab opening we talked about earlier? Hyperlinking content was largely to blame. Linking to special information that someone may or may not need is a nice gesture, but it is more likely that you are distracting them with content they are not sure they need.
Cross functional collaboration is key
Being closely involved in the discovery phase empowered the entire team to bring their talent to the table. We worked closely on these observations, sharing ideas and defining our direction as a group. This ensured every last pixel, every snippet and every letter written had the developer in mind from beginning to end. And of course, the journey continues…
If you have any feedback you’d like to share on the developer portal comment below or join the discussion on discuss.dwolla.com.
Originally published at blog.dwolla.com on November 20, 2015.
