Suggestions to improve explanations and text

[gbiggs]

The below suggestions are based on considering the book from the point of view of someone completely new to ROS, and my own experience teaching students to use new software frameworks.

• Chapter 5, Defining an action (page 63): This example mentions that the action file is already present in the basics package. Although one hopes it is obvious, the statement should be specific that the package referred to is the provided example code. This is especially true given that the topic and service examples don't mention that their message/service definition files are already present in the provided example code.
• Chapter 5, Defining an action (page 63): The find_package() call's arguments are, once again, different from previous chapters. They need to be made consistent with the previous two chapters and built up as though the reader is building their own basics package as they go through the book. The same goes for the call to catkin_package().
• Chapter 5, Implementing a basic action server (page 64): The node name in init_node() is not the same as the file name. While not a technical problem, this may be confusing for the reader because it is different from everything so far. Perhaps add a note along the lines of, "note that the node name and the file name do not need to be the same," or perhaps, "we'll be making a more advanced version of this server soon, so we'll call this one 'simple'".
• Chapter 5, Using an action (page 67): The node name in init_node() is not the same as the file name. This may be confusing.
• Chapter 5, Implementing a more sophisticated action server (page 70): The text mentions that preemption can also occur when a new goal is sent, but it doesn't mention what happens to the new goal. A short note (or link to the relevant documentation) should be added.
• Chapter 5: Earlier in the chapter, the text mentions that error handling by actions will be added later. The fancy action server has error handling, but only for checking parameters at the start. It would be good for people new to ROS to know that an abort can be performed at any time during an action's run. A brief note about this during the explanation of the fancy_action_server.py code would be enough.
• Chapter 6, Actuation: Mobile platform (page 79): The statement "which means that they cannot move in any direction at any given time" can be interpreted as "they cannot move". It should be re-worded to make it clear that the intent is that only certain directions are available at any given moment. (Even with the example given immediately after, readers often stop and re-read a sentence if they find it confusing, rather than moving on to the next sentence and hoping for enlightenment.)
• Chapter 6, Actuation: Manipulator arm (page 81): A note about the ROS messages used for manipulators needs to be added. Refer to the previous section if appropriate.
• Chapter 6, Laser scanners (page 85): "around 10 to 80 times per second (typically 600 to 4,800 RPM)": "typically" is not needed here, unless your definition of the length of a minute is variable.
• Chapter 6, Shaft encoders (top of page 86): Is it really good to say, without qualification, that counting how many times the wheels turn is often the most accurate estimate of robot motion? A shaft encoder is one of the most accurate measures of motor/axel/wheel rotation, true, but not robot motion in the case of mobile platforms (as the text itself states further on). The statement should be made more specific (i.e., state that it is "for certain robot types" or "for manipulators").
• Chapter 7, Creating a package (page 100): Example 1 is a good place to explain the concept of the simulator clock. The first light_change_time value will probably be zero, which is not what would be expected by a reader unaware that something other than the wall clock is being used.
• Chapter 7, Summary (page 108): "This brought together all of the aspects of the book thus far". Except for services and actions. Perhaps say "This has demonstrated a simple but complete robot using ROS."
• Chapter 8, Keyboard driver (page 113): Why is this example suddenly checking if the file is main? None of the previous samples did that. This might confuse someone unfamiliar with Python.
• Chapter 8, Example 8-2 (page 114): This is the first instance in the book of a subscriber callback that receives an argument other than the message. Some explanation should be given of where this argument's value is coming from.
• Chapter 8, Motion generator (page 115): The explanation of /rosout and /rosout_agg should come much, much earlier in the book (and should reference the chapter that explains them). Those two topics have been present since the first mention of "rostopic list".
• Chapter 11, Installing and running a simulated R2 (page 174): In the sample code, the reason for the "anonymous" parameter being passed to init_node() should be given.
• Chapter 11, Moving R2 around a chessboard (page 179): The hard-coded position of the chessboard is not highlighted in the code, making the connection to the discussion of hard-coding these values weak. Point out which lines in the code it occurs on at the start of the discussion.
• Chapter 11, Modelling a chessboard (page 182-4): The use of the SDF files is the ideal opportunity to teach the reader about where to put resources such as these. The reader should be given some direction on where to put SDF files in their package and shown how to find them in the spawn_chessboard node.
• Chapter 11, Example 11-8 (page 184): Although nice and short, 's' is not a good name for a service proxy variable in example code.
• Chapter 12, Acquiring images (page 194): My version of turtlebot_gazebo/turtlebot_world.launch (in Indigo) does not have the compressedDepth or theora topics. Probably just an update, but something to check for when making the 2nd edition.
• Chapter 12, Acquiring images (page 195): After 11 chapters of running Python programs, it seems a little late to mention that changing their permissions to make them executable is only one option.
• Chapter 12, Acquiring images (page 196): The discussion of the rosnode command belongs earlier in the book with rostopic, etc. It would be better to be referenced and used here the way rostopic is (this would make the book a better reference book).
• Chapter 12, Acquiring images (page 199): There is no mention that the followbot package is in the sources provided online, and will not be installed in the reader's system by default (nor is it actually installable). Actually, this would have been a great chance to introduce the tools for working with other people's packages, particularly as the code does not follow the "standard" layout described in this book.
• Chapter 13, Defining state machines with smach (page 214): The note about adding dependencies to package.xml could do with a reference to the appropriate chapter, to remind the reader.
• Chapter 13, Defining state machines with smach (page 215): The line "State 'ONE' is missing transitions: {}" in the output is probably confusing for those new to smach; a quick note about it would be welcome.
• Chapter 13, Summary (page 224): The second paragraph of the summary feels like it should be part of the body text rather than a note.
• Chapter 14, Note (page 231): Another option, which is guaranteed to be installed (since we just installed imagemagick along with ALVAR) is "display". If you're working from a command prompt, it's lighter and quicker.
• Chapter 14, page 238: The reader should be instructed to test their script to make sure it works. Otherwise they may run into problems later on.
• Chapter 14, page 239: No instructions are given for how to drive the Fetch robot. So far, the book has only talked about driving the TurtleBot using its own dedicated teleop package, and with the program written by the reader provided they have read that chapter. Most of the students I've worked with would spend an entire day trying to figure out how to teleop Fetch in this example. At least some guidance on how to teleop Fetch should be given, even if it is just "Use the program you wrote in chapter 8." A better solution, given we are using the Fetch robot simulation provided by Fetch Robotics, would be to do what their documentation suggests and use the teleop_twist_keyboard package. Then the reader would know that there is a general package available for teleoperation, and promote re-use. Yay, re-use!
• Chapter 15, Design 4 (page 266): It has been a while since the user wrote their own service, so remind them to add it to CMakeLists.txt, call catkin, etc.
• Chapter 15, Design 4 (page 267): Give the reader some brief instructions to test that their service works.
• Chapter 15, Example 15-6 (page 269): The comments are unnecessary, since much of the code we have seen before and there is a description in the body text anyway.
• Chapter 16, Simulation in Gazebo (page 290): Is it wise to use a Bitly link for the moments of inertia page? Maybe this is an O'Reilly policy, but to me Wikipedia seems likely to have more stable addresses than Bitly, which is a commercial entity in a crowded market.
• Chapter 17, Verifying transforms (page 302): Knowing about the Gazebo plugin for publishing joint states is important, but the reader also needs to know how to do this for their own hardware. Since chapter 15 didn't show how to do it for the FakeActuator, this chapter should probably at least mention where to find out how to do so. It may seem obvious how to publish joint states, but beginners with ROS will probably struggle with this - especially since sensor_msgs/JointState contains some non-obvious fields.
• Chapter 17, Configuring the navigation stack (page 311): It would be good to have a note here that the map should not be matched to the robot's laser scans yet because localisation is not yet being performed (a nice transition into the next part). I've seen questions on ROS Answers where people are confused by the map not being where they expect it to be.
• Chapter 17, Configuring the navigation stack (page 313): Loading parameters from a YAML file into the parameter server (and into a specified namespace) is newly introduced here. A brief note about what is happening would be good. I can see some beginners getting confused about topic name spaces and parameter name spaces here.
• Chapter 18, Configuring MoveIt (page 341): A one-line description of what each section of the assistant means would be good. Just saying "Nothing to do here" does not teach the reader much.
• Chapter 20, Testing a many-node system (page 368): As amazing as it may seem, some students will try to run the example test system using roslaunch, not rostest. It might be worth adding a one-liner from the shell showing launching it using rostest to illustrate that rostest is not just a library.
• Chapter 23, page 405: The third paragraph feels a little redundant.

[gerkey]

Thanks for the awesome feedback!

FYI, we're making the changes as we go in a non-public O'Reilly repo where the book text lives. When we're done, we'll re-export the code into osrf/rosbook.