1. I'd Rather Be Writing
2. Docs

Common characteristics of code tutorials

Download PDF

Code tutorials describe how developers will use your APIs and other services to achieve some end. These tutorials often involve healthy chunks of code and configuration of various services. These are the “tasks” that would be more common in end-user docs.

Code tutorials have common sections or characteristics (whether explicitly called out as such or not).

Starting with a template that lists these sections can help you gather the right information when you’re developing your own tutorials.

Activity: Analyze two code tutorials

Code tutorials often have the following sections or characteristics:

• Scenario description - the “why” behind the tutorial
• Tutorial outcomes - objectives or a demo of solution
• Solution overview - a birds-eye view of the solution
• Intended audience - assumptions about who the tutorial is for, skill level, point in journey
• Prerequisites - expectations about required items, configurations, or utilities for the tutorial (e.g., hardware devices, services set up, API keys, software, etc.).
• Steps - the tasks involved in the solution, often formatted as sections. The steps show an assembly order working up to final solution, building the code piece by piece as needed (like Legos).
• Examples to make it real - examples or personalized info included in the steps to make the steps more meaningful and understandable.
• Teaching moments - conceptual explanations peppered in along the way as asides or footnotes.
• Inline code comments - explanations inside the code about what’s going on.
• Conclusion, next steps - wrap-up, showing fully assembled code, pointing out next logical steps, linking to related tutorials.

The following are sample tutorials. Pick two tutorials and analyze them to see how many of the above common sections and characteristics you can find.

1. Twilio - How to build a chatbot
2. GitHub - Building a CI server
3. Message Buttons with Node.js
4. Dropbox - Quickly integrate file upload in your web app using the Chooser
5. Maps JavaScript API Overview
6. Searching By Seller: Reviewing Information About A Seller
7. Using the Marketing API with the Facebook Pixel
8. Create a Custom Map URL
9. Training Course: How to Build a Multimodal Alexa Skill
10. Introduction to Populating a Website with API Data
11. Video Skills Kit for Fire TV

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.