Tutorial
Template
This page provides an outline or "template" of what comprises a good
technical tutorial or "How-To."
The following two short articles contain excellent advice and are
highly recommended:
How to Write a Proper Tutorial
How to Write A Tutorial
Purpose/benefits
Begin with a section explaining the purpose of the tool or technique
that is the focus of your tutorial. You can be a bit evangelical
if you like; the idea is to motivate people by convincing them that
completing your tutorial will be worth their time. Describe how
their life will be easier or better after they finish your tutorial.
Example: Why
use JUnit?
Brief overview
Consider giving a quick summary of what they will be doing as they
carry out your tutorial. The summary can be as simple as a short
list of bullet points. This will help orient the reader to the
task and assist them in allocating time and energy to the task.
Walkthrough
This is the meat of the tutorial. Describe the procedures or
steps to be carried out by your reader. Be specific and give
detailed directions. Also explain WHY these procedures
work. The goal is not for the reader to unthinkingly follow a
cookbook, but to understand the concepts so they can solve problems on
their own.
Example: JUnit
quick start
Exercise
Provide an exercise or practice problem for the reader to complete on
their own. This allows the reader to assess whether or not they
understood your material. (Also provide a solution to the
instructor).
Example: PSP
exercise.
References
Provide external references where the reader can find more information
about the topic.