If an API is easy to find, understand, and get access to, developers can build valuable apps and integrations that much faster and easier. That was our most important goal.

Reaching that goal in an enterprise that acquires new companies every year was complex and multi-layered. We struggled with several constraints and trade-offs.

I helped my team navigate a project that was full of unknowns and dependencies by introducing the Jobs to be Done framework and building bridges with other teams.

Vision

When Salesforce acquired Mulesoft, one of the interesting new possibilities was the creation of an API ecosystem. Salesforce could provide a distribution channel to bring amazing APIs to our customers. This ecosystem would include our own APIs and partners' APIs. The name of this distribution channel was API Hub. The API Hub would provide developers the ability to quickly discover, learn, and integrate APIs into their work through a self-service workflow. The API Hub would enable customers to re-use existing services to build scalable applications as simply and as efficiently as possible.

Easily discover, learn, and use all the Salesforce APIs and services from a unified developer experience.

1. Problem

Documentation is an often overlooked user interface of the developer experience

One the most visited API documentation sites in the Salesforce ecosystem at the time.

Problems

User
  • It's hard to find Salesforce APIs because there’s not a single place to see them all.
  • Fractured experience of several sites with different user experience, styles, and content
  • Documentation locked under auth (which makes it hard to find content via Google search and limits usage)
Business
  • There's not a company-wide workflow to document, maintain or publish APIs.
  • No consistent way for Salesforce internal developers to document their APIs
  • Struggling with keeping a cohesive API experience, aggravated by acquisitions.
  • By not having easy access and discovery of internal services, product teams create duplicated services instead of leveraging existing ones.
A representation of the API Hub value proposition.

Goals

User
  • A public place to discover and consume Salesforce APIs to build scalable applications as simply and as efficiently as possible.
  • A developer experience that will guide, model, and teach developers of all the capabilities and the value and power of data integrations through APIs.
  • Easy integration of APIs into their projects, free trials, and multiple consumption models.
Business
  • A new distribution channel to document, publish and market Salesforce APIs in a cohesive way in order to stop the proliferation of standalone API reference sites.
  • Seamless documentation publishing process allowing API writers, developers, and consumers the ability to contribute to the documentation lifecycle.
  • A fantastic and accessible user experience that meets industry standards and facilitates developers' jobs.
  • An automated infrastructure that supports adding interactivity to the reference documentation and frees technical writers to write high-value content.
  • A place for internal developers to discover existing services that could be reused. This would reduce duplicated efforts, build bridges, increase usage of services across different products, and move towards a service oriented platform.
  • Eventually, a new source of revenue.

Definition of success

Initially, internal adoption. We wanted to get product teams excited about publishing their APIs and docs into API Hub. It would serve as an initial validation of our value proposition of creating a better experience for developers to discover, learn, and consume APIs.

Constraints

This project was packed with dependencies and constraints, which gave us limited space to manoeuvre and a bunch of discovery and alignment meetings to attend to get it right. To name a few:

  • Dependance on a new Developer Brand and Design System that were both in progress.
  • The API reference documentation had to leverage Mulesoft API Console, which enabled many capabilities out of the box but has some downsides in speed and user experience.
  • Needed to be closely integrated with the Salesforce Developers website, which was currently being redesigned.
  • The company went through many org changes throughout the project that created tension and issues for our team.

2. Approach

Pioneering the usage of the Jobs To Be Done framework at Salesforce was key to the project's success

We invested heavily in research for this project. We leveraged several existing internal research done on the developer persona and their documentation needs. I also led multiple research projects like competitive analysis, defining our users' Jobs To Be Done, or interviewing and brainstorming with stakeholders in order to propose a fitting and scalable solution.

Jobs To Be Done

Around May of 2020, when I was still in the discovery stage, Salesforce's leadership started introducing the Jobs To Be Done framework to the organization. I learned about it early from Design's leadership and decided to apply it on this project. At the end of 2019 I had taken a 3 months long intensive UX Research Course which gave me the knowledge, tools, and confidence to drive this design-led research project.

In the end, we formulated an exhaustive and detailed document of Jobs to be Done in a collaborative way. The output drove alignment, informed the solution, helped prioritize features, made implicit knowledge explicit and accessible by all.

API Hub's job performers, main jobs, and most important needs.

This was one of the first JTBD projects ever done at Salesforce and served as a reference and inspiration for the hundreds of teams that had to create theirs once it got announced by leadership. It was featured in town halls and presentations across the company and I unexpectedly became the unofficial JTBD advisor for a while.

High-level findings

  • Don’t bloat the Overview section. Sooner the better when it comes to showing code snippets. Several developers pointed out their industry favorites were those that immediately facilitated copy/paste from the Home Page to their CLI.
  • Developers want an API library that’s easy to navigate and locate information. When evaluating an API, they look at how intuitive the different methods are and expect extra clarity on API titles, descriptions, and naming conventions.
  • Developers want a guide to the shortest path possible to build ‘Hello World’. Several requested the ability to see/tweak code while in the Documentation.
  • Examples are extremely important, specifically in API docs. Developers want to reuse code from others and build upon it.
  • Developers love and rely on community and peer knowledge to learn new products and technologies. Some requested access to additional content such as discussion boards.
  • A feedback channel is needed between content consumers and authors. Several participants noted their frustration when documentation was inaccurate but didn’t know how to raise these issues to the writing team.

Key decision

The wrong decision to separate API docs from all the other Developer content

API Hub was originally meant to be a standalone site of the Salesforce Developers Website. This decision came back to haunt us.

We understood both the Developer Website and API Hub offered developer documentation, and in order to meet the expectations of any developer, they should be integrated. We planned to do that through the brand, information architecture, components, page design, as well as a shared navigation, search, and identity capabilities. But architecturally, they would be different sites.

The long-term vision of API Hub included a new source of revenue and marketing by monetizing Salesforce and 3rd party APIs, as Salesforce had done before with AppExchange. Building it as a separate site supported this vision.

Information Architecture representing the division between API Hub and the Developer Website

Eventually, it became really hard to justify the division, and leadership decided otherwise. This meant bringing both teams and roadmaps together when we were near the finish line.

Trade-Offs

Good
  • Allowed us to work faster and independently from the Developer Website project
  • Supported the idea of including partners API's in the future in a site that wasn't too Salesforce branded
  • Another future vision for API Hub was to generate revenue from it. Having it as a standalone site would make it easier.
Not so good
  • It created yet another separate site for developer documentation when the intention was to bring them together.
  • The designs of the Developer Website and API Hub were initially done by different designers and there were noticeable differences that made them feel like different sites when the intention was the opposite.

Information Architecture

Bringing all the dependencies and relationships to light

Right arrow

The API Hub vision posed an information architecture challenge. Within the API Hub, the challenge was to provide an architecture that was:

  • Flexible enough to support the organizational structure of different companies and brands. In Salesforce, for example, there are different sizes of API projects with diverging information architectures. Therefore our IA was broad, standard, and flexible as possible to support this particular need.
  • Scalable enough to support an API as it grows. A brand or product might start with just a couple of API references but it might scale to offer hundreds of APIs with complex connections. The IA had to support as many or as few layers as the brand required.
  • Stable enough to be intuitive and easy to use by API creators, writers, and consumers. While supporting brands, their architecture, and styles was an important part of the project, we also had to ensure a consistent and stable user experience across all the APIs. To do that, we limited our flexibility in terms of content types for the actual documentation. We would later do the same for the navigation, layout, and general page design.

Looking outwards to its ecosystem, the challenges were:

  • Creating a logical connection with related sites and supporting their future plans. API Hub had dependencies with at least five sites with their own IA, ongoing work, and future visions.
  • Considering the resource allocation of the other projects to optimize for progress, and avoid blockers or duplicated efforts. The reality of our budgets and teams had to be taken into account.

At this point, we decided to put the IA to a test by mapping a complex brand we needed to support. If it was flexible enough for that one, we believed it was fair to assert it would support other customers. And it did.

Wireframes

It was time to facilitate conversations and drive alignment through visuals

My next step was the creation of wireframes to start bringing our IA and ideas to life. It allowed our team to actually see how the IA would manifest for different customers' needs while providing a consistent UX.

Right arrow

These wireframes were distributed and presented many times across the company. From leadership to product managers, designers, and content writers. It was important for us to illustrate our proposal, receive feedback from everyone who would eventually use the site, and get them excited about it. Note: they were!

API Overview - Landing page that presents the API, its key features, and important metadata. Points to content types and other resources available for this API.
API Reference - The UI representation of the YAML or RAML spec describing the REST API. The spec includes field-level examples. The UX for the spec has built-in playground interactivity. For non-REST APIs or other developer content, this is the UI representation of reference content auto-generated from the code and following a standard template.

Key decision

The correct decision to start collaborating on a new design system to build a modern site

As I began the discovery phase of the project I learned that there was an initiative at the company of updating the Brand and Design System of Salesforce's digital footprint. That covered every site that wasn't considered a product, from the corporate website to blogs, documentation, and marketplaces, among many others. At that moment we had a decision to make, either we moved forward with the existing styles of the page (which weren't great), leveraged the design system we use for the products (which wasn't built for marketing pages and long-form content), or hopped aboard this new initiative of defining a new brand and design system. We went with the latter.

Example of a Salesforce page using the new brand.

I joined a workgroup of designers from multiple teams that would work together to the define the system in a somewhat unintuitive way. Instead of us creating the final building blocks that we would letter use for our projects, we started with our projects. We designed our own interpretation of the new brand for our sites and their particular needs.

Some components from my own interpretation of the brand.

We then shared those designs with the workgroup, identified basic components and patterns and spent months aligning on the final styles that would eventually be included in the system.

Multiple pages highlighting buttons and a annotation saying "There's an opportunity to align on these buttons"

Trade-Offs

Good
  • It allowed us to design a more beautiful and modern interface that was very well-received and inspired others.
  • Gave us freedom over the design of our components, we designed exactly what we needed.
  • The new UI worked really well with the new Developer Brand, using the same typography and color palette.
  • As part of the Design System workgroup, it gave me exposure to the work other designers were doing, which inspired me and reduced the differences across sites.
  • We weren't blocked by waiting for the new design system to be ready.
  • We weren't perpetuating outdated styles on a site that was finally being redesigned after many years.
  • We didn't have to use the Product Design System which wasn't built for marketing pages or long-form content.
Not so good
  • The design system didn't exist yet. Which meant we had to design and build tokens and components from scratch. It increased the scope of the project exponentially, for designers and engineers.
  • This method of building a design system was very hard to explain. We had multiple meetings going over the strategy.
  • Once the design system is ready to be consumed, we'll have to update the site to use the new tokens, components, and patterns.

3. Output

An intuitive and accessible user experience that facilitates developers' jobs

Landing page that groups all the Salesforce APIs. This was the page design of the Beta release.
API Overview page high-fidelity mockup
API Guide - Introduction to API as written long-form. Includes getting started content, authentication, common use cases, limits, gotchas, etc. Focuses on use cases specific to the service or product.
API Reference page high-fidelity mockup
Example of how we could show different brands in the documentation.

Implementation

Sadly, many of the proposed features got descoped during the first release planning. The project wasn't well funded and the architecture and publishing workflow took most of the engineering resources away from the final user interface.

But, the designs are there! And the PMs are excited to build them all. Now it's just a matter of time, priorities, and investment.

Next steps

As I write this case study, the project is on its way to a GA release, with a continuous rollout of new features.

4. Outcome

A successful design that achieved users and business goals, inspired the company, and won me a promotion and lead role in a strategic project

Impact

  • It was extremely well-received internally and we got many product teams excited to publish their APIs and documentation on the site.
  • An important impact of this project was the introduction of the Jobs To Be Done framework when no one in the company was using it. It served as an example and reference to other teams for many months when it got officially introduced as the new corporate methodology.
  • I helped shape the new Design System that Salesforce would use for all its digital footprint moving forward.
  • Everything I did for API Hub (research, JTBD, IA, components design, page design) directly influenced and shaped the redesign of the Developer Website.

Learnings

  • This was the first project I ever did with "wider Salesforce", out of the Heroku bubble. Heroku had been part of Salesforce for over a decade, but it still operated very differently. This meant I had to learn new tools, rituals, processes, and to my frustration... plenty of new acronyms. On the upside, it allowed me to meet and work closely with other colleagues from which I learned immensely.
  • I empirically learned the saying: "There are only two hard things in Computer Science: cache invalidation and naming things". In this case, it was definitely naming things that end up being a real struggle. We had to maintain a long glossary of terms, refer to it often, and correct each other in our language to ensure we were aligned and in agreement with every detail that would eventually be represented on the site.
  • I ended up dreading the number of alignment meetings I had to attend for this project, but I must admit they paid off in the final design and reception of our work. The upside of my dread was that I learned to create boundaries to protect my time to design.

Accomplishments

  • I had the joy of working with a wonderful group of people. We were a small group that accomplished quite a lot of important work. In the meantime, during our collaborations, we were kind, honest, playful, and accountable to each other.
  • As I was working on this project I got promoted to Senior Product Designer!
  • At the end of 2020 I was asked to lead the Salesforce Developers website redesign as well as continue leading the design of API Hub.
  • Being able to apply my recently acquired skills in UX research to pioneer the usage of the Jobs To Be Done framework at a 50K+ enterprise company was a very rewarding experience. My early championing of JTBD was key to the project's success and also provided other teams with a great JTBD example they could learn from.
  • Our team advocated, prioritised, and ensured the accessibility of our project from the very beginning. "We're not in the business of excluding anyone", I heard our architect once say.