Improve wording in Getting Started and other tutorials (backport #405)

README.md

@@ -1,28 +1,16 @@
 # MoveIt 2 Tutorials
 
-**NOTE: This repository is a new fork from the [MoveIt 1 tutorials](https://ros-planning.github.io/moveit_tutorials/) and needs your help with porting old tutorials to ROS 2.** To claim a tutorial to support the port of, see the Issues list. Thanks!
+This is the primary documentation for the MoveIt project.
 
-[See the live MoveIt 2 tutorials here](https://moveit.picknik.ai/)
-
-This is the primary documentation for the MoveIt project. We strongly encourage you to help improve MoveIt's documentation. Please consider reading the guidelines below for writing the best documentation and tutorials. However, if you are uncomfortable with any of the approaches, simply adding documentation text to your pull requests is better than nothing.
-
-These tutorials use the [reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html) format commonly used in the Sphinx "Python Documentation Generator". This unfortunately differs from the common Markdown format, but its advantage is that it supports embedding code directly from source files for inline code tutorials.
+## Contributing
 
-All content in this repository is open source and released under the [BSD License v3](https://opensource.org/licenses/BSD-3-Clause). Each individual source code file should contain a copy of the license.
+We strongly encourage you to help improve MoveIt's documentation. Please consider helping improve the tutorials, port old ones from ROS 1, and write new tutorials. We recommend you  read the quality standards below as well as the [How to Write a MoveIt Tutorial](https://moveit.picknik.ai/main/doc/how_to_contribute/how_to_write_tutorials.html) page.
 
-This repository is currently built automatically by Github Actions:
-
-- main: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Amain)
-- main: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Amain)
-- galactic: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Agalactic)
-- galactic: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Agalactic)
-- foxy: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Afoxy) (Foxy)
-- foxy: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Afoxy) (Foxy)
-- foxy: [![Deploy](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml?query=branch%3Afoxy) (Foxy)
-- foxy: [Github Pages](https://moveit.picknik.ai/): (Foxy)
+If you find an issue with the tutorials you are not able to fix yourself, please [open an issue on GitHub](https://github.com/ros-planning/moveit2_tutorials/issues/new) or open a PR with proposed changes.
 
 ## Helping with Porting Tutorials to ROS 2
-An issue has been created for each tutorial to be ported to Foxy. At the top of each tutorial there is a tag: ":moveit1:", remove the tag
+
+An issue has been created for each tutorial to be ported to ROS 2. At the top of each tutorial there is a tag: ":moveit1:", remove the tag
 after the tutorial has been successfully updated.
 
 Below are some links to help with the ports.
@@ -31,9 +19,6 @@ Below are some links to help with the ports.
 * [ament](https://index.ros.org/doc/ros2/Tutorials/Ament-CMake-Documentation/)
 * [rclcpp](http://docs.ros2.org/foxy/api/rclcpp/index.html)
 
-## Versions
-
-- ``main`` latest, changes should target this branch
 
 ## MoveIt 2 Tutorials Source Build
 
@@ -43,11 +28,11 @@ Open a command line to your your moveit2 colcon workspace:
 
     cd $COLCON_WS/src
 
-Download Moveit2_tutorials Source Code
+Download the MoveIt Tutorials source code:
 
     git clone https://github.com/ros-planning/moveit2_tutorials.git
     vcs import < moveit2_tutorials/moveit2_tutorials.repos
-    rosdep install -r --from-paths . --ignore-src --rosdistro rolling -y
+    rosdep install -r --from-paths . --ignore-src --rosdistro humble -y
 
 Configure and build the workspace:
 
@@ -58,7 +43,7 @@ Configure and build the workspace:
 
 If you want to test the tutorials by generating the html pages locally on your machine, you can use the ``build_locally`` script by issuing the following commands in the root of the moveit2_tutorials package:
 
-    export ROS_DISTRO=rolling  # 20.04
+    export ROS_DISTRO=humble  # 20.04
 
     cd $COLCON_WS/src/moveit2_tutorials
     source /opt/ros/$ROS_DISTRO/setup.bash
@@ -71,12 +56,10 @@ The local website ``<LOCAL_PACKAGE_PATH>/build/html/index.html`` should automati
  - *noinstall* skip the dependencies install step to speed up the script
  - *loop* automatically rebuild the html if a change is detected
 
-## Contributing
-
-We rely on the community to keep these tutorials up to date and bug free. If you find an issue with the tutorials please [open an issue on GitHub](https://github.com/ros-planning/moveit2_tutorials/issues/new) or open a PR with proposed changes.
-
 ### Formatting and Style
 
+These tutorials use the [reStructuredText](http://www.sphinx-doc.org/en/stable/rest.html) format commonly used in the Sphinx "Python Documentation Generator". This unfortunately differs from the common Markdown format, but its advantage is that it supports embedding code directly from source files for inline code tutorials.
+
 **Code Formatting**
 
 * These tutorials use the same [style guidelines](http://moveit.ros.org/documentation/contributing/code/) as the MoveIt project. When modifying or adding to these tutorials, it is required that code is auto formatted using [clang-format](http://moveit.ros.org/documentation/contributing/code/). To check and apply our style guidelines we use [pre-commit](https://pre-commit.com/).
@@ -147,3 +130,23 @@ To embed a video that is included in this repository, you also will use raw html
 Note that the video file is in the `_static/videos` folder instead of the same folder.
 
 [External Documentation on &lt;video&gt; tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video)
+
+## License
+
+All content in this repository is open source and released under the [BSD License v3](https://opensource.org/licenses/BSD-3-Clause). Each individual source code file should contain a copy of the license.
+
+## Build Status
+
+This repository is currently built automatically by Github Actions:
+
+- main: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Amain)
+- main: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Amain)
+- humble: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=humble)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Ahumble)
+- humble: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=humble)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Ahumble)
+
+- galactic: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Agalactic)
+- galactic: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=galactic)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Agalactic)
+- foxy: [![CI](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/ci.yaml?query=branch%3Afoxy) (Foxy)
+- foxy: [![Format](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/format.yml?query=branch%3Afoxy) (Foxy)
+- foxy: [![Deploy](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/ros-planning/moveit2_tutorials/actions/workflows/deploy.yml?query=branch%3Afoxy) (Foxy)
+- foxy: [Github Pages](https://moveit.picknik.ai/): (Foxy)

doc/how_to_contribute/how_to_write_tutorials.rst

@@ -4,7 +4,7 @@ How to Write a MoveIt Tutorial
 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>`.
+There are many additional quality standards and how-tos for contributing to the tutorials located in this repository's `README <https://github.com/ros-planning/moveit2_tutorials/blob/main/README.md>`_.
 
 Learning Objectives
 -------------------

doc/tutorials/getting_started/getting_started.rst

@@ -1,7 +1,7 @@
 Getting Started
 ===============
 
-This tutorial will install MoveIt 2 and create a workspace sandbox to run the tutorials and example robot.
+Here we will setup your environment for best running the tutorials. This will create a Colcon workspace, download all of the latest MoveIt source code, and build everything from source to ensure you have the latest fixes and improvements.
 
 Install ROS 2 and Colcon
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -40,12 +40,15 @@ For tutorials you will need to have a :ros_documentation:`colcon <Tutorials/Colc
 
   mkdir -p ~/ws_moveit2/src
 
-Download MoveIt 2 Tutorials Source
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Move into your colcon workspace and pull the MoveIt 2 tutorials source: ::
+Download Source Code of MoveIt and the Tutorials
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Move into your colcon workspace and pull the MoveIt tutorials source: ::
 
   cd ~/ws_moveit2/src
   git clone https://github.com/ros-planning/moveit2_tutorials -b main
+
+Next we will download the source code for the rest of MoveIt: ::
+
   vcs import < moveit2_tutorials/moveit2_tutorials.repos
 
 Build your Colcon Workspace
@@ -59,6 +62,13 @@ The next command will configure your colcon workspace: ::
   cd ~/ws_moveit2
   colcon build --mixin release
 
+This build command will likely take a long time (20+ minutes) depending on your computer speed and amount of RAM available (we recommend 32 GB). If you are short on computer memory or generally your build is struggling to complete on your computer, you can append the argument ``--parallel-workers 1`` to the colcon command above.
+
+If everything goes well, you should see the message "finished". If you have problems, try re-checking your `ROS Installation <https://docs.ros.org/en/humble/Installation.html>`_.
+
+Setup Your Colcon Workspace
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Source the colcon workspace: ::
 
   source ~/ws_moveit2/install/setup.bash
@@ -72,5 +82,5 @@ Optional: add the previous command to your ``.bashrc``: ::
    colcon workspace at a time, but we recommend it for simplicity.
 
 Next Step
-^^^^^^^^^^
-:doc:`Visualize a robot with the interactive motion planning plugin for RViz </doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial>`
+^^^^^^^^^
+Nice job! Next we will :doc:`Visualize a robot with the interactive motion planning plugin for RViz </doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial>`

doc/tutorials/quickstart_in_rviz/quickstart_in_rviz_tutorial.rst

@@ -3,7 +3,7 @@ MoveIt Quickstart in RViz
 .. image:: rviz_plugin_head.png
    :width: 700px
 
-This tutorial will quickly get you motion planning using MoveIt via RViz and the MoveIt plugin. Rviz is the primary visualizer in ROS and an incredibly useful tool for debugging robotics. The MoveIt Rviz plugin allows you to setup virtual environments (scenes), create start and goal states for the robot interactively, test various motion planners, and visualize the output. Let's go!
+This tutorial will teach you how to create motion plans in MoveIt using RViz and the MoveIt Display plugin. Rviz is the primary visualizer in ROS and a very useful tool for debugging robotics. The MoveIt Display plugin allows you to setup virtual environments (planning scenes), create start and goal states for the robot interactively, test various motion planners, and visualize the output. Let's get started!
 
 Getting Started
 ---------------

doc/tutorials/visualizing_in_rviz/visualizing_in_rviz.rst

@@ -1,7 +1,7 @@
 Visualizing In RViz
 ===================
 
-This tutorial will introduce you to a tool that can help you quickly understand what your MoveIt program is doing by rendering visualizations in RViz.
+This tutorial will introduce you to a tool that can help you more easily understand what your MoveIt application is doing by rendering visualizations in RViz.
 
 Prerequisites
 -------------

doc/tutorials/your_first_project/your_first_project.rst

@@ -1,7 +1,7 @@
 Your First C++ MoveIt Project
 =============================
 
-This tutorial will quickly get you writing your first ROS project with MoveIt.
+This tutorial will step you through writing your first C++ application with MoveIt.
 
 Prerequisites
 -------------