Code tutorials

Code tutorials connect the dots

Like recipes for baking goods

Reference alone incomplete

While a developer’s guide should walk a developer through the basic usage of an API and its functionality, it can’t cover every possible use of that API in a coherent way. That is where articles and tutorials come in, to teach developers tangential or specialized uses of an API, like combining it with another service, framework, or API. "The Six Pillars of Complete Developer Documentation," by Programmableweb.com (a site that has now retired)

Who writes these tutorials?

10 common sections in code tutorials

1. Scenario description - the “why” behind the tutorial
2. Tutorial outcomes - objectives or a demo of the solution
3. Solution overview - a birds-eye view of the solution
4. Intended audience - assumptions about who the tutorial is for, skill level, point in journey

10 common sections (cont.)

5. Prerequisites - expectations about required items, configurations, or utilities for the tutorial (e.g., hardware devices, services setup, API keys, software, etc.).
6. 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 like Legos.
7. Examples - examples or other personalized info included in the steps to make the steps more meaningful and understandable.

10 common sections (cont.)

8. Teaching moments - conceptual explanations peppered in along the way as asides or footnotes, like a tour guide filling in details at each stop.
9. Inline code comments - explanations inside the code about what’s going on.
10. Conclusion & next steps - wrap-up, showing fully assembled code, pointing out next logical steps, linking to related tutorials.

Activity 7a: Analyze two code tutorials

Questions?