Share Use Cases

There are probably many ways a developer can put your tool to work. Don’t make them flex their creativity muscles. Instead, share top use cases. Paradoxically, these examples help developers become more creative once you’ve seeded their imagination in the right direction.

Twilio is attempting to hit a wide audience with its current messaging, but its developer roots remain. Twilio has always done a great job of inspiring with use cases, something all audiences appreciate. The latest iteration (shown above) uses a more enterprise term, solutions, but eases naturally from high-level discussion to code-packed tutorials.

The company backs up these use cases with solid documentation that would fit well in other sections of this post. In particular, Twilio has use case tutorials within its docs, so these solutions can be discovered and described from a developer point of view.

Provide Language-Specific Content

Any modern programming language should be able to make HTTP requests. But there’s no quicker way to get up to speed than providing an SDK in the developer’s preferred language. By installing with a package manager or downloading the library, a developer can skip preparing the API calls with appropriate headers and other details. Best of all, SDKs typically simplify authentication, often the hardest part of getting started with an API.

You’ll find many big players taking the language-specific approach. APIMatic (where I’m an advisor) offers a product that generates SDKs and examples across about a dozen languages and frameworks. The technology is enabled by OpenAPI and other API descriptions (see generate API references below).

Make It Copy-Paste Easy

One of the most important jobs of documentation is to get developers started quickly. Providing code or even a curl command that they can copy and paste is the quickest way to show the value of an API.

Stripe’s documentation is often pointed to as the best, with its beautiful design and multi-column layout. Though many have copied how Stripe docs look, few have gone as far as the payments company to make its reference copy-paste friendly. From the earliest days of Stripe, every API call can be copied and pasted directly, without any intervening edits—and that includes a working API key.

You can explore what is possible in the Stripe reference and grab the exact code necessary to perform the operation. If you’re logged in, it will even include your own token (rather than the public version).

Generate API References

There are many kinds of documentation, but the foundation is an up-to-date reference. This document shows everything that is possible in black-and-white, just-the-facts format. Sure, the layout and colors might differ, but a reference is the source of truth.

Increasingly, API references are built from OpenAPI documents or other API descriptions. The OpenAPI Initiative has created an industry-driven format to define an API’s elements. These JSON or YAML documents are intended to be machine-readable and can be used in many ways. For documentation, you can use OpenAPI to generate references. Whenever any API is updated, those changes should automatically be available in an updated reference.

SendGrid’s API reference (above) has a machine-readable version of its OpenAPI document in a GitHub repo. When changes to the API are published into the OpenAPI document, SendGrid automatically runs scripts to generate correct user-facing reference documentation for its API. Many companies use an OpenAPI tool like Stoplight (an EveryDeveloper client) to maintain a source of truth from which to generate API references.

Let Developers Interact With Your API

It’s one thing to see what’s possible in a reference—it’s even better to experience it. Create an API explorer or include the functionality in your API reference.

The Dropbox API Explorer helps you quickly see the data behind API calls. Even better, it has a point-and-click token generator to let you see your own data in the responses.

Share Lessons on Your Blog

Compared to other items on this list, this one is a bit of an outlier. If you want to reach more of the right developers, you need to attract them with technical content that solves a problem. Your blog is not documentation itself but plays an important role in educating and inspiring your audience. If developers are your customers, your blog posts should speak their language.

And not just speak their programming language. You want to share best practices for your specific technical area. Explore specific use cases beyond merely how it’s accomplished, but why you’d build your way. Technical blog posts are a key piece of developer marketing that works.

LogRocket is a front-end monitoring tool. It helps development and product teams monitor performance, usability, and errors. However, its blog topics are much more expansive. The company publishes multiple posts per week with general front-end education. Its content is not focused on its product, but rather the problems its ideal developer customer experiences.

LogRocket treats its blog like a publication that developers would read even when they aren’t shopping for monitoring. That way, when they do have a problem that LogRocket solves, they’ll remember who taught them important front-end lessons.

Keep Engineers Learning

Blog content, usually 1,000-2,000 words, can offer targeted lessons to developer readers. Yet, the problems that technical products solve are often much bigger than can be covered with your typical blog fare. This is where deep, educational guides can take over. Rather than sitting within your documentation (there are other options for that type of content), these guides help explain problems—and solutions—without leveraging a specific product.

Gremlin’s Chaos Monkey Guide may be the best example of this type of content. At over 18,000 words, it’s treated like an entire section of Gremlin’s site. The guide itself is split into multiple pages and each covers one area of Chaos Engineering. Gremlin’s product helps teams implement the chaos monkey pattern, but this guide *does not* dig into its implementation. 

This guide ranks well for relevant, high-volume topics, so it likely brings evergreen traffic. In addition, Gremlin links to the guide in blog posts, onboarding emails, and in prominent navigation. You wouldn’t want to dilute the power of this format with too many, so start with one strategic guide of high potential. Then, focus your efforts to make it successful.

See more examples of these guides (which we call Signature content).

Upgrade Your Developer Experience

Perform an audit of your existing developer portal and content, making a list of potential areas for attention. Perhaps you have a getting started guide, but it needs some updates to be simpler or focus on a different area of your developer product. Maybe you have a list of use cases already in mind that you can share to stoke your audience’s imagination. Or, think about some new articles on your blog if you haven’t published anything in a few months… or maybe even a year.

Take one or two of these areas on to improve your documentation today. It doesn’t have to be a lot of work—a documentation team can help you make the most impactful changes quickly. With consistent attention, you’ll have better docs and happier developers.

If you still aren’t sure where to start, assess the current state of your developer experience with our free DX Quiz.