Your Developer Documentation Is a Conversion Tool, So Why Aren’t You Treating It Like One?
March 3, 2021
One of the most attractive features of a product-led business is the low cost of acquisition driven by organic user signups and self-serve conversions. We even created a new SaaS metric to measure this phenomenon and the underlying health of the growth engine driving your company. For developer-focused software, product-led models have become so common that the broader market now expects it.
To build a thriving organic growth engine, you don’t just need a strong product that users can derive value from quickly—you must also message the value of that product (to get users pumped up about trying it) in a number of different ways.
Think of it this way: The website is how people engaging with your brand will discover your product, through mentions from friends or on social media. That’s one way of achieving virality, and it’s core to gaining users and customers early on—especially early adopters. It’s the front door to your software.
Your developer documentation is how people discover your product via organic search, StackOverflow, or other developer communities. It’s essentially the side door to your product. At the same time, it acts as a bridge between your application and the ideal user journey—so it’s extremely important for complicated product offerings. As a result, it needs to express the value of your product just as much as any website would.
So, I fired up the ol’ Wayback Machine to check out the changes to documentation that companies like Snyk, Stripe, Mulesoft, Confluent, DataBricks, and more made over time to align their front-door and side-door channels.
1. Keep UI as simple as possible for folks who are just starting out
I get it: Developers are too cool for splashy colors and sans-serif fonts. Most organizations keep documentation uniform by leveraging the standard left-hand navigation and helpful feel that you expect from, well, product documentation.
That’s all well and good until your product starts to develop more nuance, or if you have an open source vs. paid version.
Let’s examine how Snyk has handled it over the years:
Even in Snyk’s early days (2017), they differentiated by organizing documentation with clickable images and allowing users to customize their experience by coding language.
Now Snyk’s core documentation nav is extremely welcoming to newcomers. Current docs have strong segments and a cohesive call to action to get started. It’s also straightforward for experienced users to search for a solution to a problem with the search bar.
Stripe, who I believe is the gold standard of documentation perfection, has also taken the controversial move of abandoning the left-hand navigation on their docs landing altogether, reverting to clear, color-coded calls to action.
As a new user, I immediately understand what Stripe does and what I need to do next.
Even Stripe’s core docs are laid out in a pleasing, website-esque way, making them easier to navigate than the infinite scroll I encountered on many other developer-focused sites.
2. Use value-based language
More often than not I see businesses shy away from using any “salesy” language in developer documentation. I admire this purist outlook, but I also think it can inhibit a developer’s understanding of what the product could do for them.
For example, in my past work interviewing back-end engineers, one of the most common questions I heard was “Why should I care about this product/feature?” or “What’s in it for me?” Product documentation should explain how to use a product as well as why that usage is going to be valuable to a developer—not only to get them to eventually pay for the product, but also to keep them engaged throughout the setup process.
It’s rare to see this value-based language done well, but I particularly like DataBricks’ approach:
In the example above, you can see how DataBricks calls out the “why you should use this product” question in the blue note boxes throughout the documentation. This color coding is helpful because it allows developers who are familiar with the offering to simply skip over it once they’ve seen it.
Another good example comes from Cypress.io:
I particularly like how direct the team’s language is in the first sentence of this chapter of documentation. They have a feature and how you can add onto it later. To make this page even stronger, I would elaborate on why recording tests is helpful. Will it save the user time? Help them catch bugs faster? Not super salesy, but context that I’d love to have as a reader and user!
My recommendation for all businesses looking to make their documentation stronger as a side door to the product: Take a step back from the technical writer or product manager owning documentation, and add a product marketer into the mix.
Some of the more successful models I’ve seen have the technical writing, followed by a “glow-up” of sorts from a more go-to-market focused product expert. MailChimp is a great example (below):
That dynamic duo will help your documentation stand out.
3. Make sure documentation is discoverable
I won’t call out any specific examples, but I’ve seen a number of growing startups putting their product documentation on Notion or similar platforms. That’s fine, but you have to ensure that your particular instance is discoverable by search engines.
Going back to my introduction for this piece, documentation can be a wonderful side door into your product. And ensuring that documentation is public and discoverable by search engines—not just from your homepage—enables that natural growth engine.
I’d love to hear from the community about which tools have excellent documentation, and how you discovered them. Let me know what you think on LinkedIn or Twitter.
Header image by #WOCinTechChat.