How-To Guide

The How-To Guides are distinctly different from tutorials in that they are directed towards a different audience. How-To Guides are Problem-Oriented and assume the reader came to this page to answer a specific question. These pages possess these qualities:

  • a series of steps

  • a focus on the goal

  • addressing a specific question

  • no unnecessary explanation

  • a little flexibility

  • practical usability

  • good naming

In a tutorial, you carefully guide the reader through doing a set of steps with the goal of learning. Readers who are following tutorials don’t yet know the terms or concepts well enough to ask specific questions. Readers of How-To guides are already using MoveIt but are looking for instructions on doing something specific.

Name Answers a User’s Question

How-To guides answer very specific questions and should capture Google searches. For that reason, naming is very important. Examples of good names are:

  • How to Visualize Collisions in MoveIt

  • How to Grasp Objects with MoveIt

  • How to Run MoveIt with UR5

  • How to Fix a Segfault

  • How to Migrate from Foxy to Galactic

  • How to Run in Gazebo

  • How to Set Up a New Robot for MoveIt

  • How to Use the MoveIt RViz Plugin

  • How to Teleop a Robot Arm with a Controller

Goal-Focused and Practical

For these guides it is important that you focus specifically on solving the problem the user came to the site for. Because these users already have a deeper understanding of core concepts, you should present the user with some options when they will need to make a decision with tradeoffs. You should state what the assumed pre-requisites are in the introduction to the How-To Guide. By doing so, you avoid duplicating instructions on this site and you allow users who already know the prerequisites to jump right into solving their problem.