You can probably imagine yourself midway through a complex technical tutorial. You have multiple terminal windows open. Your browser has tabs aplenty. Your fingers have memorized the “Ctrl-F” pattern as you search for the next step.
The best dev tool and API companies aim to provide a better developer experience with tutorial content. We’ve collected six examples to encourage you to educate and inspire developers!
Provide Code and Context in One Place
A great programming tutorial provides both code and context. You need to know what steps to perform and why they’re important. Stripe engineered an immersive tutorial format for its code samples. It provides code and context in a single page, pulling readers deeper into the experience.
Already frequently mentioned in conversations about the best API documentation, Stripe used its popular two-column approach in a new way with its tutorial. A typical step-by-step guide takes the left column, while code examples are located to the right. More notably, the code emulates an editor with a tabbed interface. Finally, a preview pane shows how the HTML and CSS render.
Developers can click through to explore, though the files are not editable. The real power of this tutorial is clear as you click or scroll through the steps in the left column. The section of code is highlighted on the right side in the appropriate file.
Twilio is often mentioned alongside Stripe for great developer experiences. The communications API company explored similar tutorial innovations, which led us to highlight how great APIs have one thing in common—they’re always improving.
Drip Out Learnings Through Daily Emails
Tutorial innovations don’t need to involve large engineering efforts. If the goal is to help developers layer on additional understanding, that can be achieved by frequent, smaller lessons. That’s the angle Dan Abramov took with Just JavaScript.
In Dan’s case, he sends an email every day, unpacking another JavaScript concept. Each includes an exercise or question, which is answered further down in the email.
This simple approach is not the final format Dan has in mind:
Over time these emails will evolve into an in-depth, interactive, fun, multimedia course that explains these powerful mental models for programming with JavaScript.
However, by starting here, he’s proven you don’t need to be fancy to provide a good learning experience.
Make the Training into a Game
Would you choose to play a video game or read a textbook? For most developers, they’d grab the controller every time.
Playing Crash Bandicoot and realising how good technical writing and cirriculum is similar to good game design. Note this has nothing to do with gamification, which is a hollow version of game design.
— Dan Abramov (@dan_abramov) February 22, 2020
In fact, the long term plan for Dan Abramov’s JavaScript emails is to become “The Crash Bandicoot of JavaScript courses.” A prime example of a game as developer education is TwilioQuest, the 8-bit-inspired program from Twilio.
Once a web-based experience, Twilio went desktop in 2019 with a cross-platform downloadable game. Developers (and aspiring devs) can complete missions while learning about languages, Twilio products, and more.
Screencast With Annotations and Quick Links
When many developers think of tutorials, they don’t imagine written words. As much as the EveryDeveloper team loves writing, we know sometimes a video walkthrough tells a more complete story. Done well, screencasts can help you cover both written and visuals.
Paircast is screencast software built specifically for showing code. It records your screen, microphone, camera (optional), and changes within your git repository. Then it provides transcription of everything you said and puts it in a Markdown file. After some cleanup, you have a written and video tutorial, with an interactive timeline.
Code Editor with Embedded Screencast
The goal of most tutorials is for developers to follow along with each step, learning as they go. They will retain more of the information if they try it themselves. The team at Scrimba make that easy with an in-browser code editor that includes embedded audio and video to complete the screencast experience.
In addition to watching an instructor type out code, developers can edit and run the Scrimba tutorial code right in the browser.
Courses with Short, Punchy Screencasts
Some tutorials can be a slog to get through. Whether written or video, you want to provide a sequence of quick wins to encourage developers. JavaScript instruction site egghead provides a great example.
Each lesson is about two minutes long. By necessity, it is incredibly focused on a single topic. These are often part of a larger course, but the egghead style encourages these lessons to work on their own. There’s even a how to egghead site if you want to try your hand at this instruction method.
Now that you’ve seen how others have pushed the envelope of education, where will you go with your developer tutorials?
No matter what, you’ll need to fill your guide with educational developer content. EveryDeveloper can help you create memorable, useful tutorials.