Documentation Version
You're reading the documentation for a stable version of MoveIt that is not being developed further. For information on the recommended version, please have a look at Main.
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.