Herald Docs Center
A Docs Center with 50+ docs, step-by-step guides, and interactive demos to make integrating with Herald a breeze.
UX
Technical Writing
As an early stage company, it’s fundamental to our growth to launch with new customers quickly to drive activity. At the end of Q1 2022, our average time-to-integrate was 12 weeks, far behind what we needed to reach our usage targets. I prioritized our Q2 roadmap to emphasize ease of use, focusing on solutions to help developers integrate with our API quickly rather than launching new features.
After some research, we found that the biggest contributing factor to our integration time was the need for developers to reach out to our customer success team to answer specific questions, rather than issues with our actual API design. Many of our customers have offshore engineering teams, so receiving an answer for a single question could take an entire day. The key project for Q2 was to launch Herald Docs, a documentation hub that walks developers through our API’s core concepts, nuances, and step-by-step guides to integrating with each endpoint.
I created our Docs Center in Webflow, with a structured side-bar broken out by Endpoint, and a robust search functionality. The insurance industry has a lower bar regarding technology, and our docs have set us apart from what developers are used to in as far as documentation in insurance goes. We’ve received raving reviews from developers, citing our docs as the best in the insurance industry and on par with the pioneers of API documentation like Stripe and Plaid.
Herald has upwards of 20 endpoints, a list that's continuously growing. Most endpoints are only relevant in the context of how they are being used in a larger workflow, interacting with other endpoints. Reading a single piece of documentation for each endpoint won't get an engineer very far, what's needed is use-case based documentation, step-by-step guides across multiple endpoints, and core concepts being explained before a single API-call is made.
As an aggregator other APIs, Herald's core concepts can seem incredibly complex, with different endpoints containing 50+ key value pairs. It's not an ideal developer experience to sit down and read an encyclopedia. I wanted to boil our high-level documentation down to the absolute bare essentials, with more comprehensive, use-case driven documentation to act as supporting materials as needed.
We're constantly developing new features and endpoints, and needed a process to maintain this documentation regularly and in a consistent tone and style. Different types of features and use cases require different materials.
.jpg)
Currently, Herald has over 50 published docs and guides, and I've written about 75% of them myself. I've instated a detailed doc-writing process, and no feature is considered released until it's accompanied documentation is published.
Our documentation starts with a "Getting Started" section, focusing on Heralds core concepts that span across multiple endpoints, and detailing how endpoints play with each other. There are different types of docs and guides, some more focused on content to drill down into principals and concepts, while others are heavily comprised of sample requests and responses to act as integration guides. Nearly every doc is paired with an abstracted visual aid to communicate the endpoint or scenario in a minimal way.
The docs center is explicitly detached from our API reference, which is managed in a tool called Stoplight. Our docs walk through using multiple endpoints together and real scenarios, linking out to the relative API-reference as needed.
