On building the next wave of user friendly documentation for engineers and non-engineers alike.
Your docs are artwork by the way, really inspirational for us at Blip.
— Seth Fenster, Co-Founder @ Blip Labs
It started last year, after we received an email with the above quote from a customer. The Museum of Selected Documents—that's what we started calling our documentation website. There are probably few things that are more boring in the tech world than docs. Equating it to art is of course ludicrous and is probably why the joke stuck for so long.
We started calling the content of our docs—paintings, and me—the curator, museum director, artist. While this definitely made a somewhat uninspiring job of writing documentation somewhat less uninspiring, there was a more profound change taking place.
We started treating documentation with more respect once we had viewers (engineers using our docs), which benefited from an experience that required careful curation.
Once we put our UX glasses on, it quickly became apparent that documentation is one of the first touch-points with existing customers and prospects for new features. So documentation became an integral part of product development and one of the deliverables before any feature was greenlit for release.
Once we delivered fleshed-out docs before product releases, I was able to better spot inconsistencies and suboptimal implementations. This meant that documentation started slowly creeping from the tail end of our product development iterations to the forefront and became one of the early deliverables and a blueprint used by developers.
And all of this started from a joke from a customer.
The Docs Experience Is Broken
Once we started thinking about the user journey more, we uncovered two important findings:
The standard docs experience is overwhelming and exhausting
This works fine while the product is still MVPish and the customers are tech-savvy early adopters. However, very quickly the product expands, new docs are added (usually by developers, product managers) without someone there to manage consistency, optimize for readability, and for a great user experience. Eventually it becomes overwhelming and exhausting for the newer batch of customers which are not at the same level of excitement to integrate as the previous one.
Oftentimes our user journey in the docs for a customer starts with their product/project manager
The other learning was that somewhere at the end of the sales funnel, customers start reading the docs. The people doing it are product or project managers, tasked with evaluating how much it will cost to integrate with us or with one of our competitors. And the PM has different questions compared to a developer, such as:
Where in the customer's flow should Argyle be implemented?
How should we on-ramp and off-ramp users from the Argyle experience?
How should we present terms of services for the Argyle part of the flow?
What front-end and back-end resources will we require to integrate?
etc.
So after figuring out that our docs are overwhelmingly being read by PMs, we realized that a different approach is required
The Palace of Knowledge
Nobody ever got fired at Argyle for taking inspiration from Stripe.
— Me
As we move to the third iteration of our documentation website (codename: The Palace of Knowledge), the user journey is front and center.
The alpha dog in the documentation space is Stripe. I think most people out there who are trying to improve their docs will find a lot of inspiration on their site. We found ours on their docs homepage.
Solutions
The standard docs experience is :
A quickstart guide
The rest of it
Our current docs user journey can be summarized as:
What is your use case?
Here is an end-to-end guide (a Solution) for your use case. It's divided into two parts:
Scoping - answers all the questions the PM might have (or should have) about integrating with Argyle.
Implementation - gives a technical overview to the PM and provides a roadmap for the developers.
The rest of it, conveniently linked to from the Implementation part of each Solution.
Solutions are our way to hold a customer's hand to find the relevant assets until they are ready to go at it on their own.
We Are Just Getting Started
This is already working. We get a lot of feedback from our customers that our docs are top-notch. Recently, one of our prospective customers opted to forgo doing a comparative integration with us and a competitor, citing "professional documentation" as one of their decision factors.
Once you realize that documentation is a powerful tool not only for customer support, but also for product development and driving sales, then the sky is the limit. I'll make sure that nobody is ever fired for copying Argyle.
To check out Argyle's newest version of the docs, please visit: argyle.com/docs
Be first to get industry insights and news from Argyle.