Docs for Developers

One of the unique aspects of how we operate at Outseta is everyone on the team does customer support. Everyone, no exceptions.

Our intention is to keep our team as small as possible and only hire really excellent people—we want to show that a company of 20 people can compete with a company of 100. We want people to have their questions resolved the first time they reach out as opposed to the endless cycle of escalations that's so common in SaaS companies.

I think we're doing a pretty good job here—the quality of our support has become an often cited differentiator for us.

While that's the case, the time that our team spends answering support tickets comes at the expense of time we could spend elsewhere—it's time that we're not spending on marketing and it eats away at our product velocity, too. In order for Outseta to scale as we want it to, we need to enable people to solve their own problems as often as possible without requiring the invention from a member of our team.

Few things contribute more to customer self-service than having great documentation. Suitable documentation isn't good enough—with our organizational model, our docs need to be great.

To that end, Benedicte suggested I read Doc for Developers—it's a guide to writing great technical documentation written by a bunch of smart folks who have created documentation for companies like Google and Stripe.

While it was definitely a good read, it's not lost on me that this probably isn't the page turner you're looking to bring on your next vacation—so I thought I'd share my notes. That's what the remainder of this post is—I've lightly edited my notes to provide some context and make them most useful to you. But this post is just as much me documenting my thoughts for myself and our team—we're going to adopt a bunch of this stuff into our own documentation processes.

You'll get a bit of a teaser in terms of some of the new features we'll be building into our knowledge base product, too. To start, we gave our own docs a light design refresh that you can check out here.

Now on to my notes—the headings below refer to the chapters of the book.

Understanding your audience

The book starts out by encouraging you to get very clear on who your users are and what the goals of your documentation are. While that may sound obvious, it's a good starting point.

Who are Outseta users?

• Technical founders building SaaS products
• Non-technical founders building membership sites

We support both user types today and should make it clear when writing our docs who each article is for.

Goal of our documentation

• Primary Goal: Onboard new users so that they integrate payments and charge for access to their software or content as quickly as possible
• Secondary Goal: Enable users to adopt each of Outseta’s core tools

Being an all-in-one product, onboarding is of critical importance—when we get this right customers convert at a higher rate and rarely churn. Beyond that, the vast majority of our support comes from onboarding customers who are integrating Outseta with their products for the first time—this is the most important thing for us to get right.

Primary common goal of our customers

• Charge for access to their products

Outline of user needs

The book then encourages you to outline all of your users' needs. I'm not going to do so here—as an established company, we have a good sense of this based on our existing knowledge base and support tickets.

Planning your documentation

This section outlines different types of documentation. Whenever we sit down to write something, we should first identify what it is that we’re drafting. Going forward, we'll identify each article that we're working on as belonging to one of the following categories.

Code comments + READMEs

• I don't have a great sense of developer expectations around code comments and READMEs, so this is an area where I'll lean on Benedicte

Getting Started Documentation

• Most important for us—I think our current emphasis on setting up payments and authentication is correct.
• Keep it as BASIC as possible

Conceptual Documentation

• Explains concepts and ideas—how your service works to customers
• Ex: What are Outseta’s sign up and login embeds?

Procedural Documentation

• Tutorials and how to guides
• Task oriented, step by step
• Specifically call out prerequisites at the beginning

Reference Documentation 

• Think of our API documentation. The book suggests this should be a standalone resource and auto-generated from our source code.
• My feeling is we need more explanation and examples

Troubleshooting Documentation

• We don't have much in the way of troubleshooting documentation today—we handle through support tickets.
• Ex: We get a lot of tickets referencing a “Domain is required to initialize Outseta script” error message. What do you do if you get that error message? We can be more proactive in helping customers understand how to troubleshoot common errors like this.

Drafting Documentation

Before we write any new article, we're going to list 3 items at the top of the post.

• ‍Audience: Developers using Outseta who know how to use REST APIs‍
• Purpose: Describe how to create a subscription using Outseta’s REST API‍
• Pattern: Procedural Documentation

The items below are then the major sections / formats that would be included in any given article.

Headers

• Headlines should summarize the document’s goal
• Keep them brief and skimmable
• Should start with a verb for procedural documentation

Paragraphs

• Provide context around what you’re doing
• Limit the use of paragraphs as much as possible

Procedures

• Step by step, task oriented

Lists

• Bulleted items where the order doesn’t matter.
• Ex: A list of website builders that Outseta integrates with

Callouts

• A way of drawing visual attention to an area of the page
• Warnings, Cautions, Notes

Editing Documentation

• Break up long documents! Shorter is almost always better.
• Define a peer review process
• Create a small style guide for common phrases (Ex: Sign-up vs. Sign Up)

Integrating Code Samples

Code Sandboxes

• Valuable because they give the developer an opportunity to play with the code freely
• Book advocates for auto-generating code samples, but having humans rewrite code comments to make them reader friendly and provide missing context

Adding Visual Content

Video Content

• Interestingly the book sort of bad mouths video content when it comes to documentation—difficult to create and maintain, easily goes out of date.
• No-coders have shown more of a preference for video tutorials compared to our developer customers.

Gathering and integrating feedback

• Consider a way for users to send you email feedback about a specific doc
• Consider a way for users to rate the article as helpful or not

Measuring Quality

• Hemmingwayapp.com can be a useful tool in measuring conciseness

Organizing Documentation

• I like how we currently organize much of our documentation around the core features of Outseta—Billing, Auth, CRM, Email, Help Desk, etc.
• I also think “Getting Started” makes sense as a category
• Beyond that, we probably have some work to do
• Most users start their search within a search engine

Maintaining and Deprecating Documentation

• Assign each document owner—if everyone owns it, no one owns it
• Consider adding a “Last Modified” date to each doc to document the freshness of the content
• How do you reward / incentivize document maintenance?

Those are my rather raw notes as I moved though the book—I think there's a lot of value in just getting the basics consistently right. Things like labeling your docs as conceptual versus procedural documentation, being clear on the audience and purpose of each post, and consistently starting headlines with a verb go a long way in creating a cohesive set of docs.

Next up, here's a wishlist of items that we need and/or plan to build into Outseta's knowledge base.

Action items—things we need or can improve

• Analytics—the number of views of each article (to know what docs are getting traffic today).
• Capture search queries (so we know what users are searching for that we don't have docs for yet).
• Documentation needs to become a more formal part of our release process (it's pretty informal today).
• Add a peer review process (we currently have a "Waiting Review" status on articles).
• Create style guide for common phrases (Ex: Sign-up vs. Sign Up)
• Add a way for users to rate an article and provide feedback
• Add ability to assign an owner to each doc
• Consider adding a "Last Modified" date to posts
• How do we reward document maintenance?
• We need a visual design for callouts within the documentation
• Improve visual design of code snippets within Outseta's knowledge base

I hope this post is useful in giving you glimpse of some of the behind the scenes work that we're doing to make sure our documentation meets the needs of our customers. If you're working on your own docs, Docs for Developer is definitely a good read that's been helpful in giving us some shared language and a consistent approach to working on our docs.