Skip to content

Commit

Permalink
Fixes for Concepts: How-To Guide (moveit#286)
Browse files Browse the repository at this point in the history
Co-authored-by: cmelliott2 <[email protected]>
  • Loading branch information
cmelliott2 and cmelliott2 authored Jan 15, 2022
1 parent 3e1c370 commit 6aae45f
Showing 1 changed file with 12 additions and 12 deletions.
24 changes: 12 additions & 12 deletions doc/concepts/how_to_guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,31 +13,31 @@ These pages posses these qualities:
* 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 know the terms or concepts yet to ask specific questions.
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.

Names Answer a User's Question
Name Answers a User's Question
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

How-To guides answer very specific questions and should capture Google searches.
For that reason the naming of them is really important.
An example of some potentially good names are:
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 Run MoveIt with UR5
* How to Fix a Segfault
* How to Migrate from Foxy to Galactic
* How to Run in Gazebo
* How to Setup a New Robot for MoveIt
* How to use the MoveIt RViz plugin
* 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
Goal-Focused and Practical
~~~~~~~~~~~~~~~~~~~~~~~~~~

For these guides it is really important that you focus specifically on solving the problem the user came to the site for.
Because these users have a deeper understanding though you should present the user with some options when they will need to make a decision with tradeoffs.
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.
That way you can avoid having multiple copies of isntructions on this site and allow users who already know the prerequisites to jump right into solving their problem.
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.

0 comments on commit 6aae45f

Please sign in to comment.