Fixes for tutorial on how to write tutorials (moveit#273)

Co-authored-by: Tyler Weaver <[email protected]>
Co-authored-by: Jack <[email protected]>
Co-authored-by: Cassidy Elliott <[email protected]>
Co-authored-by: Mike Lautman <[email protected]>

doc/how_to_contribute/how_to_write_tutorials.rst

@@ -1,9 +1,10 @@
 How to Write a MoveIt Tutorial
 ==============================
 
-This guide explains how to write Tutorials for MoveIt documentation which are one of the most useful contributions you can make because they are the first thing many new users see.
-This guide is primarily intended for use by employees at PickNik Robotics to assist in standardizing tutorial documents but can be used by any contributor who wants to submit a new tutorial.
-If you are looking for how-to guides for using MoveIt, you can find them here: How-To Guides.
+This guide explains how to write tutorials for the MoveIt documentation.
+Tutorials are one of the most useful contributions you can make because they are the first thing many new users see.
+This guide is intended for any contributor who wants to submit a new tutorial.
+If you are looking for a how-to guide for using MoveIt, you can find one :doc:`here </doc/how_to_guides/how_to_guides>`.
 
 Learning Objectives
 -------------------
@@ -14,26 +15,24 @@ Requirements
 ------------
 - Ubuntu 20.04
 - ROS 2 Galactic
-- MoveIt2
+- MoveIt 2
 
 Steps
 -----
 
-1. Fork the MoveIt2 Tutorials repository (https://github.com/ros-planning/moveit2_tutorials.git) and start a new branch with an intuitive name (e.g. jack/how-to-tutorials)
+1. Fork the `MoveIt 2 Tutorials repository <https://github.com/ros-planning/moveit2_tutorials.git>`_ and start a new branch with an intuitive name (e.g., ``jack/how-to-tutorials``).
 
-#. Create a new file in the ``doc/tutorials`` directory with a ``.rst`` extension. The title should start with a concise description and end with "Tutorial" (e.g. "Writing MoveIt Tutorials Tutorial").
+#. Create a new file in the ``doc/tutorials`` directory with a ``.rst`` extension. The title should be a concise description (e.g., "MoveIt Quickstart in RViz").
 
-#. Add a link to your tutorial on the tutorials page: :doc:`/doc/tutorials/tutorials`
+#. Add a link to your tutorial on the :doc:`tutorials page </doc/tutorials/tutorials>`.
 
 #. Write the introduction using reStructuredText (.rst) using the following guidelines:
 
-   - The title should have the same name as the file.
-
    - The introduction should explain the purpose of this tutorial and the intended audience.
 
    - If you think people may regularly find this particular guide by mistake, add links to the proper resource.
 
-#. Write the specific learning objectives (i.e. what will the reader know when they finish reading this tutorial).
+#. Write the specific learning objectives (i.e., what will the reader know when they finish reading this tutorial).
 
 #. Add any system or equipment requirements for this tutorial so users know if this tutorial is appropriate for them.
 
@@ -43,7 +42,7 @@ Steps
 
 #. Add a link to the next tutorial the reader should follow.
 
-#. Submit the new page as a PR to the MoveIt2 Tutorials repository (https://github.com/ros-planning/moveit2_tutorials.git).
+#. Submit the new page as a PR to the `MoveIt 2 Tutorials repository <https://github.com/ros-planning/moveit2_tutorials.git>`_.
 
 Template
 --------
@@ -53,30 +52,30 @@ Template
   <Title>
   -------
 
-  <Brief description of the tutorial with image showing what will be accomplished>
+  <Brief description of the tutorial with image showing what will be accomplished.>
 
   Background
   ----------
 
-  <Explination of what the user should have already done before this tutorial>
+  <Explanation of what the user should have already done before this tutorial.>
 
   Steps
   -----
 
   1. <First Step>
   ---------------
 
-  <This should describe an action that the user should take such as creating a ROS project or typing up some code>
+  <This should describe an action that the user should take such as creating a ROS project or typing up some code.>
 
-  1.1) <Explination First Step>
+  1.1) <Explanation First Step>
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  <Use substeps like this to walk the user through an explination of what they did>
+  <Use sub-steps like this to walk the user through an explanation of what they did.>
 
   1.2) <Action First step>
   ^^^^^^^^^^^^^^^^^^^^^^^
 
-  <Use a substep like this to describe running the new code and what the results should be>
+  <Use a sub-step like this to describe running the new code and what the results should be.>
 
   2. <Second Step>
   ----------------
@@ -91,9 +90,9 @@ Template
   Next Step
   ---------
 
-  <Link to the next tutorial here>
+  <Link to the next tutorial here.>
 
 Further Reading
 ---------------
 - :doc:`/doc/how_to_contribute/how_to_contribute_to_site`
-- Concepts page: :doc:`/doc/concepts/tutorials`
+- :doc:`MoveIt Concepts: Tutorials </doc/concepts/tutorials>`