Activity 7a: Analyze code tutorials
I'm giving an API documentation workshop in Los Angeles, California, on January 23, 2020. You can view details on EventBrite here.
Input needed: I'm currently conducting a survey about trends in developer documentation for 2020. If you write docs for developers, please take this survey. (You can view the ongoing results viewed here.)
Activity 7a: 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.
- Stripe - Sending emails for failed payments
- Twilio - How to build a chatbot
- GitHub - Building a CI server
- Message Buttons with Node.js
- Dropbox - Quickly integrate file upload in your web app using the Chooser
- Searching By Seller: Reviewing Information About A Seller
- How to Make a Heatmap with Mapbox GL JS
- Using the Marketing API with the Facebook Pixel
- Create a Custom Map URL
- Training Course: How to Build a Multimodal Alexa Skill
- Introduction to Populating a Website with API Data
7/151 pages complete. Only 144 more pages to go.