Jump to: navigation, search

Tutorials are one of the three parts of high quality documentation. A tutorial should guide a user or developer through a single use case of the software. For example, if your software has a user management system, you may want a tutorial that guides a user through:

  • viewing the user list
  • searching the list
  • editing a user's details
  • adding a user
  • removing a user

Jacob Kaplan-Moss suggests that good tutorials should have the following characteristics:

  • They should be short (no more than 30 minutes from start to finish)
  • They should be easy but not too easy
  • They should demonstrate how the project "feels"

Tutorials should take less than 30 minutes to go from start to finish because users may not be very invested in your software yet. When considering this link, make sure you're not overlooking any steps that extend the time longer for a newer user.

In regards to ease of use, tutorials shouldn't assume the reader is incompetent. They need to be easy enough to be performed by the targeted user but complex enough so the user actually learns something valuable.

Demonstrating a project's feel is a slightly more difficult requirement. They key is that a tutorial shouldn't lead a reader or viewer to get comfortable with the tutorial and then go into the project and be just as lost as when they started. It's important to put information in the tutorial into it's proper place in the larger whole of the project.

Be creative with your tutorial! A wall of text is not a very interesting tutorial. Use diagrams, pictures and videos to reinforce and teach the user in addition to any text you have.