From 99df38e336f18100f6355d42562ad8022ff4bc84 Mon Sep 17 00:00:00 2001 From: Cassidy Elliott Date: Fri, 14 Jan 2022 17:11:05 -0700 Subject: [PATCH] Fixes for How To Write How To Guides (#280) Co-authored-by: cmelliott2 Co-authored-by: Jack Co-authored-by: Cory Crean --- .../how_to_write_how_to_guides.rst | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/doc/how_to_contribute/how_to_write_how_to_guides.rst b/doc/how_to_contribute/how_to_write_how_to_guides.rst index 7d8b6df5a1..3a4900e202 100644 --- a/doc/how_to_contribute/how_to_write_how_to_guides.rst +++ b/doc/how_to_contribute/how_to_write_how_to_guides.rst @@ -2,7 +2,7 @@ How to Write a MoveIt How-To Guide ================================== This guide explains how to write How-To's for MoveIt documentation. This guide is primarily intended for use by employees at PickNik Robotics -to assist in standardizing how-to documents but can be used by any contribitor who wants to submit a new guide. If you are looking for +to assist in standardizing how-to documents but can be used by any contributor who wants to submit a new guide. If you are looking for how-to guides for using MoveIt, you can find them here: :doc:`/doc/how_to_guides/how_to_guides`. Learning Objectives @@ -14,20 +14,20 @@ 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-write-how-tos) +1. Fork the `MoveIt 2 Tutorials repository `_ and start a new branch with an intuitive name (e.g., ``jack/how-to-write-how-tos``). -#. Create a new file in the ``doc/how_to_guides`` directory with a ``.rst`` extension. The title should start with "How to" followed by the specific question being answered (e.g. "How to Write a MoveIt How-To Guide"). +#. Create a new file in the ``doc/how_to_guides`` directory with a ``.rst`` extension. The title should start with "How to" followed by the specific question being answered (e.g., "How to Write a MoveIt How-To Guide"). #. Add a link to your guide on the appropriate how-to guide page: - - User guides: :doc:`/doc/how_to_guides/how_to_guides` + - :doc:`User Guides ` - - Contributors guides: :doc:`/doc/how_to_contribute/how_to_contribute` + - :doc:`Contributor Guides ` #. Write the introduction using reStructuredText (.rst) using the following guidelines: @@ -37,15 +37,15 @@ Steps - 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 how-to). +#. Write the specific learning objectives (i.e., what the reader will know when they finish reading this how-to). #. Add any system or equipment requirements for this how-to so users know if this how-to is appropriate for them. -#. Layout the individual action steps and do not leave out necessary intermediate steps. +#. Lay out the individual action steps and do not leave out necessary intermediate steps. #. Create a "Further Reading" section that links to amplifying information. -#. 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 `_. Template -------- @@ -55,29 +55,29 @@ Template ------- - <Brief description of the How-To Guide with image or GIF showing the outcome> + <Brief description of the How-To Guide with image or GIF showing the outcome.> Learning Objectives ------------------- - <List of things the user will learn> + <List of things the user will learn.> Requirements ---------- - <Explination of what the user should understand. Unlike a tutorial these are stand-alone and can assume the user has much more background.> + <Explanation of what the user should understand. Unlike a tutorial, these guides stand alone and can assume the user has much more background.> Steps ----- - <A list of steps to take to solve the problem> + <A list of steps to take to solve the problem.> Further Reading --------------- - <A list of links to related content on and off this website> + <A list of links to related content on and off this website.> Further Reading --------------- - :doc:`/doc/how_to_contribute/how_to_contribute_to_site` -- Concepts page: :doc:`/doc/concepts/how_to_guide` +- :doc:`MoveIt Concepts: How-To Guide </doc/concepts/how_to_guide>`