Tutorials should:

  • give people easy wins,

  • be quick (a new user should experience success in less than half an hour),

  • demonstrate how your project "feels",

  • introduce high-level concepts from your project (i.e. views, models and controllers in the case of MVC web framework).

It's important that the frustration is biggest at the beginning of using library because the user usually don't know even the basic concepts from your project. Therefore, it's really important to reduce friction in tutorials.

Good API references are really bad tutorials (i.e. man documentation).

Be step-by-step ("step one", "step two" sections in tutorials).

See also