rviz/Reviews/2009-10-21_Doc_Review

Reviewer:

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of your Package, i.e. for the expected usages of your Stack, which APIs will users engage with?
2. Are all of these APIs documented?
3. Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage), and are the indexed in the right places?
4. If there are hardware dependencies of the Package, are these documented?
5. Is it clear to an outside user what the roadmap is for the Package?
6. Is it clear to an outside user what the stability is for the Package?
7. Are concepts introduced by the Package well illustrated?
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
9. Are any mathematical formulas in the Package not covered by papers properly documented?

For each launch file in a Package

1. Is it clear how to run that launch file?
2. Does the launch file start up with no errors when run correctly?
3. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?

Concerns / issues

Tully

• I don't see any documentation of plugin API. Is this purposeful?
  • [Josh] - Yes. The plugin API is yet considered public/stable. It was only put in (too quickly) to remove a bunch of invalid dependencies from rviz.

Eitan

• rviz/UserGuide

  • Displays
    • It would be useful to go into a bit more detail about what a Display Status means. Does it mean something different depending on the display type? If so, this should be noted and each display type section should document what status means. If not, just explain the status stuff here.
    • [Josh] Status is general will show similar things. The text of the status itself should be descriptive enough to not have to document each one. I've added a bit about the status to the page though.
  • Configurations
    • Clarify that the global configurations menu corresponds to the built-in configurations that are available. Putting the picture below is almost clear enough, but not quite.
    • What is the default configuration folder? Can I change it?
    • [Josh] Global/local configs have been removed for 0.4, I'll note that in the docs.
  • Views
    • You use "FPS" in a sentence before you actually spell out that it stands for First Person Shooter.
      • [Josh] Removed
    • Are views saved when I save my configuration or do I always have to load them?
      • [Josh] Clarified
  • Coordinate Frames
    • Couldn't get more than the first 4 seconds of the video to play for some reason... make sure that it works for you
      • [Josh] Works for me, not sure why it wouldn't work for you -- might want to talk to Scott

    • Perhaps a link to tf to explain what coordinate frames are for those who don't know

      • [Josh] Done
    • Might be worth highlighting "frame3" in the "map" coordinate frame pucture to show how the perspective is about to change
      • [Josh] I removed the screenshots entirely, since the video shows it much better. Does that seem reasonable?
  • Tools

    • Might be worth linking to the navigation stack for setting goals and poses.

      • [Josh] Done
  • Plugins
    • How do I go about creating a plugin?
      • [Josh] Added a note in the plugins section mentioning that it's not a stable/supported API.
    • What are the current plugins available and what do they do? Should I just be using the descriptions in rviz for this information?
      • [Josh] The only currently fully-supported plugin is the builtin one -- the others are in sandbox/unreleased stacks. Once we have a larger plugin ecosystem I'll need to come up with a way of linking them from the rviz page.

• rviz/Troubleshooting

  • Add something about rviz getting really slow spanning multiple monitors because the second one may lack hardware acceleration
    • [Josh] Done

Matei

• Marker Tutorial says it is still under construction; should we include this in this review?
  • [Josh] Yes, sorry, I finished it a while ago but forgot to remove the note
• I found the term "Properties window" confusing. Nowhere in rviz does it say "Properties", that pane is actually titled "Displays". Maybe refer to it as "Display Properties Window" or just "Displays Window".
  • [Josh] Done
• what exactly is contained in a "Configuration"?
  • [Josh] Added
• same for a "View", maybe make clear it is camera location, orientation, view mode, etc.
  • [Josh] Added
• Frames
  • the video example of how frames work is pretty good
  • the image examples with map/frame3 I found not informative at all
    • [Josh] I removed it in favor of just the video -- does that make sense?
  • after reading the docs, I am still not 100% sure how frames work. For example, what is the purpose of a "target frame"? if I want my camera to look like it's following the robot, would I not achieve the same thing by setting the robot frame as base frame, and letting the rest of the world go by?
    • [Josh] Did the video clear it up? I think it's one of those things people just won't really understand until they've played around with it/seen it in motion.
• key shortcuts seem mostly dedicated to a specific app (2d nav),although this is not really a documentation issue, the key shortcuts are well explained here.
• what is the purpose of displaying the time? Does the time affect what is displayed and what not? If so, how?
  • [Josh] Added some comments about this.
• Troubleshooting
  • does well to address the most common problem, "nothing shows up"
  • should also mention that a common reason for that is that something does show up, but the camera is simply not looking at it. User has to drag around for a while, or zoom in/out to see if something's there
    • [Josh] Added
  • the solution proposed for nothing showing up due to tf problems works well, but suffers from the camera singularity problem we were just looking at. Again, not a problem with the documentation, but I expect to be a fairly common issue with many users, especially before they get comfortable with tf.
    • [Josh] Not sure what can really be done about this other than fixing the camera
  • has item numbering problems (0.1, 0.0.1, etc)
    • [Josh] Fixed

Conclusion