Designing docs for Merge's Unified API

Hello world!

My name is Simeon Lee and I’m the Founding Designer at Merge. I’m thrilled to be sharing our design adventures in the public view. I’m most excited to share the inner workings and decisions of a designer sprinting across the user-facing surfaces of a high-growth seed stage company with a lot of design needs.

What does Merge do? Merge hosts the world’s first Unified API for HR, payroll, recruiting, and accounting. Whether you have customers that are currently using Trinet or ADP or Freshteam (or Hibob or Lever or Greenhouse or JazzHR or Quickbooks or Sage…), you no longer need to have hordes of engineers on staff and unending roadmap carve-outs for long-tail integrations. Integrate once with Merge’s Unified API, and we sync your users’ data with all of the integrations on our platform. We save you tremendous amounts of time, money, and tears.

Related: 12 unified API examples

Designing for an API

Even though creating documentation is not widely considered “exciting” work, our docs serve a critically important function to the success of our business: they document and disambiguate Merge’s Unified API. In writing this post, I’m hoping to shed light on the design decisions that culminated in the latest major release of our docs last week.

First off — How do you generally design for an API? There are multiple levels of design inherent in an application programming interface, but to simplify, I consider good user-focused design to focus on:

1. Engineering semantics, whether it be naming things to be relatively self-documenting or having a simple experience to implement full, predictable CRUD workflows.
2. Documentation that removes the unpredictability in an idiosyncratic application programming interface.

At Merge, code semantics are owned by our engineers, and so our engineers have needed to become designers themselves. This means building and testing integrated applications in various languages and integrating them with our Unified API, just like our customers. No small feat, but reliability is paramount at Merge!

I’ve been in charge of designing and fleshing out the other side of our API — the documentation. This means creating the onboarding experience, mapping out the information architecture of our API, collaborating with our engineers to ensure content is accessible and accurate, and iterating the visual style of the docs to be appealing and maintain a high level of quality in our API product.

Our Docs Journey Begins

November 2020

When I first arrived at Merge, I was surprised to find that our docs lived inside the Merge dashboard web app. I would learn this decision was primarily to hide our product details while in stealth.

Our first version of our docs lived in our dashboard

I didn’t agitate to move our documentation outside of our dashboard immediately. With minimum viable experience in mind, I spent my first few months improving the quality and content of the documentation. This included polishing the onboarding experience so that new developers would have an easy 2-step guide to integrate Merge into their product. Step one of the guide featured dropping our Merge Link component into their frontend; step two featured integrating their backend with Merge using one of our many SDK’s. Both steps featured testing utilities to signal a successful integration with Merge (something familiar: make the red blinking light go green through a successful request).

Related: A guide to reading API documentation

Docs Go Public

March - April 2021

There was so much to do in the early days that even when it was clear our docs were functionally different from our dashboard and should live in a separate context, we couldn’t prioritize rearranging our frontend assets until much  later.

After several months, we finally moved our docs into our landing page. This made our docs viewable to prospective customers (no signup required) while also making it publicly accessible via search engines. (Did I mention Merge was now announced to the whole world?)

With the move, I wanted to visually differentiate our documentation from our dashboard web app. Our dashboard featured a white navigation bar, so I hastily made the left navigation sport a contrasting dark gray gradient and gave it a minimal home page. Aside from that, the design and information architecture of the documentation remained largely unchanged.

This older version of our docs contained information architecture weaknesses

In this widely viewable version of our documentation, we began to receive negative user feedback regarding poor informational architecture. The next challenge we would need to tackle would be to aid the user in uncovering the content they sought regarding the CRUD workflows for the many object classifications we have across our HR, payroll, recruiting and accounting integrations.

Latest Docs Revamp

May - June 2021

In our latest major revamp of our docs, we went back to the drawing board and interrogated the content of our documentation as that would inform our layout. Remember: Form follows function!

Our documentation featured several groupings of information:

1. Merge Link Quickstart
2. SDK Overview
3. API Reference

Our API Reference broke down into these sections:

• Basics
• ATS
• HRIS
• Accounting
• Supplemental Data

The first two major groupings — Merge Link Quickstart and SDK Overview — constituted our “Get Started” guide. The final group of information — our API reference — was essential for customers to understand our standardized data model and available CRUD operations.

The biggest problem with our previous documentation’s API reference was that the CRUD operations for all of our standardized data models were on one long scrollable page. When we began to receive negative customer feedback regarding our docs — in particular, the difficulty of discovering information in this massive page — it pushed us to rethink our information architecture and overall design. We rapidly moved towards a new visual system for our documentation — see the results below:

Our latest docs home page

In this latest redesign of the docs, I exchanged out the dark gray style in favor of a muted gray theme with the mildest slant of blue hue to imbue a subtle modernity.

The new gray

Our biggest change was the creation of an information hierarchy that subsisted across a series of new nav bars. We chose to feature a primary top navigation, a secondary top sub-navigation, and a left navigation with vertical accordions used to dissemble standardized data objects and CRUD operations.

From there, we broke out the CRUD operations for each “Common Model” (what we term our standardized data types) onto separate pages:

Our Common Models broken out on separate pages

Assigning separate colors to each HTTP request method (e.g., GET, POST, PATCH, DELETE) helped create a delineation in the navigation between disparate concepts and establish a familiar pattern throughout the docs in the navigation and content.

With the separation of topics (remember — no more single long scrollable page), it was essential for our developer to implement elegant and fast interactions as our user flipped through each element. Brendan Goggin — our full-stack wizard — implemented stimulating, artfully eased transitions making our docs feel like a seamless, organic, and delightfully explorable experience. Truly a marvel to click around and play with.

Interaction design preview

More Little Things

An assortment of other small information hierarchy improvements were made to improve clarity and help the user think less when looking for the information they sought.

The first was creating a more sensible design for child relations. Our Common Models have a nested hierarchy for certain relations — such as that between parent objects like Candidates and child objects like Phone Numbers (which aren’t simple string fields on the parent because they need extra fields to handle type differences).

For child objects, instead of having a whole separate section for them, we chose to simply show them in-place within the parent object themselves. See example below with Phone Number, Email Address, and URL:

Code Snippets

Our code snippets all previously sported a dark blue theme. This included both executable code and API example response objects.

Previously, all our code snippets featured this dark style

However, API documentation has a lot of code snippets of different types — some executable, others example response objects — and having them all the same style made parsing and scanning lots of content burdensome. We created delineation and hierarchy in the information presented amongst our code snippets by keeping our executable code snippets dark and making our response examples and object schemas light:

Our latest example response snippets now feature a new, distinguishing style

Pending Changes

One weakness we quickly discovered with our new design was that people couldn’t rely on CMD+F’ing their way to the information they were seeking. Still, even that one unexpected benefit of the monopage documentation was limited in scope: only experienced users knew what they were looking for. Newcomers were out of luck. We’re solving this in our new docs by simply adding a search bar.

Conclusion

Designing documentation isn’t typically thought of as flashy work, but this project was a great exercise in information architecture, which breaks down into the artful use of typography pairings, subtle color cues, whitespace importance, and content groupings.

I think great design is about stripping away the unnecessary and letting idiosyncratic design notions get out of the way to present only that which is important to the user as quickly and sensibly as possible. The documentation of our Unified API is truly our most important user-facing product — without providing our customers an understandable map, it’s possible they may never successfully arrive at their desired destination.

Our startup’s mission is to provide our users the ability to integrate fast and integrate once. Great design will be our secret weapon in winning over our customers’ developers and ultimately the booster rocket which will propel our impact upon the API economy to stratospheric heights.

Merge provides a Unified API to transform how B2B companies implement user-facing integrations. Learn more about building once, building better, and building faster — here.

‍