Great examples of programming tutorials — and the lessons we can extract from them

A16z general partner Martin Casado noted in his 2017 talk that the disaggregation of the app into sets of APIs is a major new opportunity. We’re definitely seeing this play out three years later.

SmartBear — the creators of Swagger (you might be familiar with their OpenAPI specification) — surveyed 3,000 API practitioners and consumers from a range of industries, finding that 76% of organizations are developing both internal and public-facing APIs.

APIs are exciting, invaluable, and only getting more widespread. Everything from the scrappy APIaaS startups to Fortune 50 companies are working on APIs.

The vital link between an API and users is the reference material — documentation, examples, tutorials, code snippets, videos, and so on. These can be the difference between alienating users and introducing even novice programmers to your product

I haven’t found many resources for writing a great API tutorial (contrary to the mountains of guides on writing great documentation), so here we are.

Summary

Here’s what to expect from this guide:

• We’ll overview eight excellent examples of tutorials, and what makes them tick.
• We’ll cover tutorial navigation best practices.
• We’ll take a look at how to structure your tutorial.
• We’ll go over clarity and appealing to your target audience.
• We’ll look at a few great code highlight tools.
• We’ll see how interactivity and media can make a tutorial “stickier”.
• We’ll answer the question, how much time should you invest in your API tutorial?

Where am I coming from?

I’m a technical copywriter who started developing nearly four years ago. My go-to resources for learning Python were MIT’s free compsci course with Eric Grimson and John Guttag, Learn Python the Hard Way, and (still) my favorite (single-video) YouTube tut ever: David Beazley’s Learn Python Through Public Data Hacking.

They all had this “jump into the fire” mentality that got the basics and the potential of the language drilled into my head. Lots of fun and experimentation. Beazley’s course also gave glimpses of how powerful APIs could be. Excuse the cliche, but it opened up a world of possibilities (la-di-da).

The resource I seek out before diving into any new API was is usually a tutorial or a quickstart guide. I’ve found some solid, practical, and fun tutorials, but there were also atrocities that left me running to official documentation, the source code, or to another API altogether (this recently happened while I was looking for a payment solution for my SaaS — I ditched PayPal and beelined to Stripe after taking a look at the former’s documentation).

Examples of great tutorials

Over the years I’ve found some great tutorials — not just for APIs, but for frameworks, programming languages, and various scenarios. The lessons from each of the below examples can easily be applied to an API tutorial (after the examples, we’ll overview how to implement these lessons).

Tutorial Example #1: Digital Ocean

Digital Ocean’s How To Install Nginx on Ubuntu XX.XX has been around for years — it’s a living document that has been viewed over 700k times, and it’s a reference I look back to often when launching a site. Here’s what makes it stick out:

• There are different versions of the tutorial for different operating systems.
• There are six languages available. Props for accessibility.
• There’s a floating table of contents on the left that makes it very easy to navigate.
• The steps are broken up into small chunks with plenty of example code.
• There are screenshots of what you’d see while you’re starting your project — not just code.
• Like I mentioned above, it’s a living document. It’s constantly updated, and it’s a beautiful example of how to create a tutorial people will be coming back to for years.
• It probably serves as a solid driver to Digital Ocean’s products.

Tutorial Example #2: W3

Many of us have come across w3schools.com, with its easy-to-grok modular design, ubiquitous Try it Yourself code examples, and inviting design.

• The JavaScript guide I linked in the header is both a tutorial and reference — which makes it very sticky (something users are likely to keep returning to for years).
• There are interactive examples for everything, they’re all practical, and they’re easy to change and play around with.
• Everything is split up into super-digestible chunks.
• Navigation is dead simple — again, it’s both a tutorial series for learning a solid foundation while doubling as something you’ll be going back to for reference.
• It just feels cozy, doesn’t it?

Tutorial Example #3: Google

Nothing too fancy for Google’s Python tutorial. It’s even a bit wordy compared to the other tutorials out there. But it’s still way at the top for me for several reasons:

• There are videos by Nick Parlante to accompany all the text sections. They’re a decade old, but people are still raving about them. Take a look at one of the videos to see why.
• Though it’s wordier, you get a solid foundation of the language from the get-go.
• The navigation is very well laid out. There’s a general TOC on the left, and a floating Contents box on the right. You’re never lost while reading.
• There are fun exercises you can navigate to at any point.

Tutorial Example #4: Real Python

Real Python’s strongest facet is its attention to detail — tutorials are crafted to be as legible, helpful, and simple as possible — even when the topics get more complex.

• Tutorials have a TOC at the start and a floating TOC on the right.
• Bullet points and simple code snippets really help pace the content.
• Additional colored info boxes and nice touches like comparison tables (see below) help both readers diving deeper and those simply skimming the tutorial.

Tutorial Example #5: Toptal

Toptal wants you to hire their experts, and the experts want to get hired. This mutual incentive translates into a solid engineering blog from Toptal professionals with impressive credentials — and one or two decades of experience thrown in. Experts put in a lot of care into their educational material. One nice example is from an M&A banker and startup CFO who extols the use of Python for finance. Here’s what’s special about this tutorial:

• The author understands the target audience well. Instead of jumping into the code after a brief introduction, he provides an executive summary, quotes from The Economist and the CEO at IDEO, personal use cases, an overview of why the language is ideal for these cases, and other points CFOs (and consequently Excel power users) might find useful before diving in.
• The actual tutorial focuses on applying a Monte Carlo simulation on a simplified discounted cash flow valuation model. Again, the author is in-tune with the target audience.
• The tutorial is much wordier than other examples in this list, but that works well for the readers he’s targeting.
• Despite the lack of a TOC and the wordiness, the tutorial is well structured, easy to follow, and includes excellent resources at the end for those who want to dive deeper.

Tutorial Example #6: Twilio

Twilio’s tutorials aren’t my favorite on this list, but there are some things they do really well.

• You can select your preferred programming language at the top, which is convenient as, really, most readers will be using just one.
• Twilio begins with a high-level summary of what the finished product will do, which lets the reader know what to expect.
• While there is no clear TOC, and the example snippets are chunky, Twilio still manages navigation well. To move to the next step in the tutorial, you click on a button below each section (“Click me to move on to the next step!”)
• When you click the button, a new section appears below and the code example on the right pane changes. This is a really nice touch that keeps the tutorial from looking overly complicated and stuffed with snippets.
• They even gracefully handle 135-line snippets by blurring surrounding code, going through it bit by bit (see below).

Tutorial Example #7: Stripe

Stripe has long been cited as an inspiration for its well-structured, well-written documentation, despite the product being a bit difficult to integrate from the get-go for beginners. Their quickstart guide is no different. Here’s why:

• The development quickstart summarizes the three steps you need to integrate Stripe into your site, then dives into each step.
• There’s a floating TOC on the right for easy navigation.
• When you change the language in any code snippet, the language changes in all the other snippets. Some API quickstarts are missing this simple functionality, so it’s a nice touch.
• Examples of response objects are conveniently truncated, keeping the quickstart from looking intimidating for those skimming through.
• Next steps at the end lead to overviews developers may be interested in, continuing the flow instead of cutting things short and making readers search around for where to go next.

Tutorial Example #8: Django

Django’s Polls App tutorial is a classic for a reason. Actually, a number of reasons:

• Each section features a TOC at the start, on the right-hand side.
• It’s practical and it’s fun — just search GitHub for Django Polls and see the amount of proud variations people have put up on their accounts.
• Snippets aren’t just well-highlighted, the correct filename is shown above the code — this is very helpful.
• The tutorial is split into sections, and while some are quite lengthy, bullet points, bolded keywords, and code comments help things flow smoothly, despite taking several hours for beginners to complete.
• In the process, readers not only build a functioning app they’re proud of, they learn about the Django framework — and even the Django developers’ philosophy.

Navigation

You might have noticed some commonalities between the tutorial examples above — the most prevalent being the TOC. (Unfortunately, if you’re reading this piece on Medium, the platform doesn’t have a TOC feature — which is insane, given the sheer number of API tutorials published here.)

TOCs — whether they’re at the top of the tutorial, floating on the side as you scroll down, or (preferably) both — help with stickiness. In other words, a TOC transforms your practical example into a reference readers can come back to. Content that you put this much effort into shouldn’t have the ephemerality of a tweet — it should be something people keep coming back to for years.

Structure

We’ve seen a number of structures in the examples above — from Django’s lengthy sections, to one-pagers like Stripe’s quickstart, to interactive educational blocks in W3’s tutorials. But what they all do impressively well is explain one thing — and one thing only — per section/block, and they make sure you understand all that’s required before proceeding.

You see it in Real Python: “Set Up a Python Virtual Environment,” “Create a Django Project,” “Generate and Apply Initial Migrations,” and so on. Google’s old-school Python tutorial dives deep into lists, strings, sorting, and other fundamentals, and makes sure you have a solid understanding of each. And in Digital Ocean: “Adjusting the Firewall,” “Checking your Web Server,” etc.

Clarity

All the tutorials above can be grasped by beginner programmers, despite the complexity of each. The Toptal tutorial does this really well, targeting an audience with a financial background and easing them into programming with practical examples they can relate to. I can imagine Excel power users reading this tutorial and seeing the power of Python and Jupyter Notebooks for the first time, being completely blown away by the potential.

A good rule of thumb for clarity (and navigation and structure) is, would you use it for yourself if you didn’t know everything about your API? For example, I documented my deployment process in a series on interconnected Google Docs — this has saved me many hours of Googling. I come back to it often, even just to look at certain pieces. Will your API tutorial save the reader hours, drawing them back when they need to reference certain sections? Django, Real Python, and Digital Ocean do this really well — I always come back to these when I forget something… before going to any official documentation.

Code Examples

If you’re writing your API tutorial on a Medium-based blog, use GitHub Gist to embed highlighted code snippets. Don’t use screenshots for code. Other than Gist, here are a few other libraries and tools I like:

• Prism: The most popular code highlighting JavaScript library.
• Highlight.js: My preferred code highlighting JavaScript library.
• Andrew Sun’s Code Highlighter: An online code highlighter that supports a large number of languages… and actually allows tabbing inside the text box — and inline CSS.

Interactivity & Media

We’ve seen Google’s Python tutorial use videos as a complement to the text tutorial. They can be consumed as a standalone tutorial or in unison with the text. Readers likely go back to both at different times. Adding videos and screenshots — and interactivity, like with W3’s tutorials — creates a stickier, more reference-like tutorial.

How much should you invest?

I believe the best mindset to adopt here is: you’re not writing a blog, social media post, newsletter, or anything that may be read once and then forgotten. You’re writing something people will come back to several times, maybe even over several years.

Digital Ocean’s Nginx tutorial is a testament to this: six years and going strong, with hundreds of thousands of views. The authors update the tutorial for each Ubuntu release and address other Linux distributions. It’s a living document that acts like documentation for a specific task. With that in mind, you’ll want to spend as long as you need to to create material that readers can keep coming back to.

Remember the essentials

The essentials for API tutorial writing are:

• If the platform you’re writing on allows it (cough, Medium, hark), include a TOC at the top, and something that floats (🎈) as the reader scrolls down. This helps create stickier content readers can refer to later.
• Each section or block in your tutorial should explain ONE thing, and do it well. Explain everything the reader is required to know in order to proceed to the next thing, and then move on to the next thing.
• Assume your audience is just beginning to program, and use examples they’d be familiar with. Ask yourself, is this something I’d keep referring to if I didn’t know anything about the API?
• Include highlighted code examples (that readers can copy), but don’t stuff snippets with too much code. If you have to, comments are a great way to keep things flowing smoothly.
• Interactivity, screenshots, and videos should complement the text guide. They shouldn’t be a necessity, but they should be a helpful reference in themselves.
• Invest as much time as you need to make the tutorial itself a useful reference for readers. The goal is to get readers to return multiple times, either for clarification or if they forget something.
• Your tutorial is a living document — update it when necessary.
• Add any next steps at the bottom — keep the readers moving!

About Me

I’m a technical copywriter who helps startups, large consultancies, and Fortune 500s translate complex concepts into digestible material — including API tutorials. If you have any questions, qualms, or suggestions, feel free to contact me at aleks [at] smechov [dot] com. Twitter: @AlexSmechov. LI: https://bit.ly/2ZB5K9S