How to make your code examples in your documentation shine like Stripe

At Write the Docs Portland 2018, Technical Writer at Stripe Larry Ullmann shared his experiences of producing code examples for a developer audience.

In his talk, he told the audience how Stripe makes its code samples so brilliant. It’s partly a result of the team’s unrelenting emphasis on its primary audience – developers.

Making your code examples shine

We know that Stripe is a developers-first company. That’s why it’s interesting to take a deep dive into just how the company creates its code samples. Documentation is a key part of Stripe’s endeavor to engage developers with its products.

What stands out about Stripe code samples is their beautiful design, and how it’s so easy to switch between different languages right in the docs.

The docs are truly interactive, and you can even make an API call directly from the page.

It’s important to hire the right technical writers to produce such high quality documentation. Larry says, “I know when I’m dealing with a natural writer or a well-trained writer when they ask ‘Who is the audience?’” According to Larry, this is principally how Stripe recruits its technical writers.

Treat code like docs

Since code examples are written by multiple people in the team (and not necessarily the technical writers), this means the docs can lack consistency. This makes for a bad UX.

Many of the principles of technical writing can be applied to your coding samples. Larry advises to treat your code like your writing – in the sense that you should even have a style guide for your code.

Some examples of what you could include in your style guide are your naming syntax conventions and placement of parentheses in your code. Also, your indentation rules and use of quotes.

Content and code tell your story, as both are a way of communicating with your users. In a way, it’s treating your code like docs. Let your code show your audience what you value.

“At Stripe we value clean, well-designed code using today’s best practices,” says Larry. This is how Stripe conveys its values.

“A good product documents itself, but our users don’t need products. They have problems and they need solutions. Documentation is this solution, so we map our solution to their problem.”

Know the audience for your docs

You also have to know who your audience is to write the best docs.

Are they junior developers or are they mostly using WordPress plugins? Don’t discriminate against more entry level users, but at the same time don’t go automatically go to the lowest common denominator.

Don’t view developers as the enemy who will just complain about your efforts. Have empathy for your users so you can produce better developer docs. This may all be quite obvious, but great UX is not usually the norm in these situations. Predict the questions your users will ask in advance and answer them in your docs.

Also, make your code copy and paste-able for the best UX. The examples should work then and there on the page using a tool like Runkit (how Stripe generates its interactive API calls). It shows the results right there using the API, and you can edit the inputs right in the docs.

They use RunKit (https://t.co/dqAQ7g3S74) for runnable code examples. #WritetheDocs pic.twitter.com/w4HTrSrhTI

— Jay Elmore (@jelmore) 8 May 2018

Solving the challenge of scale

On the other hand, it can be difficult to maintain such a large number of code snippets.

This number of examples is only growing as Stripe expands operations, and each example must also work in eight different programming languages. Users must be able to copy and paste each one successfully as a working example.

According to Larry, the answer is to automate with in reason and build empathy with your users. Generate code examples programmatically – since it takes too long to do them by hand. This is the practice of future-proofing your code samples.

Ideally, write a tool that makes code examples for you (as Stripe has done). Then, if you want to change your template for your knowledge base, you can automatically generate the code again – saving a lot of time and effort. Then, test your examples to check if they’re working or not.

Final remarks

Stripe has broken the mould when it comes to developer docs. It was useful to take a peek behind the curtain and see what we could learn from the masters.

For Stripe, the answer does boil down to creating your own tool to automatically generate and update code samples, which may not always be possible for everyone. You can also follow a style guide for your code to make examples easier to understand.

This is crucial because Stripe is building a global economic infrastructure for the internet. The company began initially with credit card payments and has now expanded to billing and security. Stripe gives developers the ability to create payment platforms without struggling with dense, poorly structured API references.

Not everyone will need to operate at the scale that Stripe does when it comes to code samples, but it’s useful to keep these best practices in mind.

At the very least, we can standardize both our docs and code samples for a better experience.

Check out our write-up of another Write the Docs talk discussing how to conduct research with your users. Listen to Larry’s full talk on YouTube. 

Images by Kay Smoljak. This work is licensed under a Creative Commons Attribution-Non Commercial-ShareAlike 2.0 Generic License.

KnowledgeOwl is our very own knowledge base software, perfect for technical writers of many stripes. Take it for a free spin.