How to write a tutorial

This content was developed at the Mozilla Drumbeat Festival during a break-out session on MDN resources for web developer education.

Summary of approach

Tutorials and documentation should be one and the same, especially to facilitate learning. Typically, learners don't read lengthy documentation, and need concrete, complete examples which they can adapt. And they need it quickly.


  • Start with the 'finished example' first. Show the reader exactly what they should create with the example provided. Use a screenshot.
  • Describe the specific use case of the example.
  • Show users where they can modify and adapt to see different effects.
  • Give the complete code for download, which can be used directly by a novice- not just the snippet or clipped example.

Specific to screencasting

  • Don't use background music throughout the screencast. The audio competes with the viewer's attention.
  • Don't move your mouse around the screen unless directing to a specific action.


Document Tags and Contributors

 Contributors to this page: jswisher, nearlythere
 Last updated by: jswisher,