Tutorials are hard to create without understanding your user first. Try to put yourself in their shoes.

• What are they trying to accomplish?
• Can you write a tutorial that gets them half-way there?
• Is your tutorial written in terms that will help them find it?
• Can I break a tutorial into multiple steps, where each step is easy to accomplish and teaches something valuable?

Take, for example, tf. What is a user trying to accomplish with TF? Well, there's probably at least two types of users:

• people trying to setup their robot with TF
• people trying to use TF-based data

A good, multi-stage tutorial might be to teach the user how to setup TF on a two-wheel, differential drive robot with a laser rangefinder on its base. This type of robot is simpler than the PR2 and also will probably have many similarities to the robot they are trying to port it to.

1. Tutorial: Setup your base laser with static TF transforms
2. Tutorial: Integrate your robot's odometry using dynamic TF transforms
3. Tutorial: Transforming data from your robot's base laser
4. Tutorial: Setup a moving sensor using dynamic TF transforms
5. Tutorial: Transforming data from a moving sensor

It's important to provide users with a tarball at the beginning of each step if they need to use code from a previous step. This way, each type of user can feel free to skip ahead to the tutorials that interest them. For example, a user trying to setup a robot may only be interested in Tutorials 1, 3, and 5. A user interested in just using sensor data may only be interested in 2 and 4.

Template

It's impossible to provide a one-size-fits-all template, but here's a general outline

1. If this Tutorial is part of a multi-step tutorial, link to the other steps

2. What does this tutorial teach? What Stacks/Packages/PR2 functionality/etc... does it address? If you're trying to teach them specific API calls, highlight what those are so they can focus on the important parts.

3. If this tutorial builds upon code from a previous step, include a link to the necessary code
4. Walk the user step-by-step through your tutorial. Include code snippets as appropriate to minimize the user's typing. Make sure that the user can tell which step they are on in case they lose track by providing clear details as to what they should see.
5. Make sure that at the end of the tutorial the user can tell that they are done. Is there some command they can run that gives them specific output? Is there a screenshot of what they should see on their screen?