sound_drivers/Reviews/2009-09-28_Doc_Review

Reviewer:

Instructions for doing a doc review

See DocReviewProcess for more instructions

1. Does the documentation define the Users of the Stack, i.e. for the expected usages of the Stack, which APIs will users engage with?
2. Are all of these APIs documented?
3. Do relevant usages have associated tutorials?

4. Have all Packages in the Stack been API reviewed?

5. Does the Stack conform to the StackDocumentation guidelines?

6. Are there Packages in the Stack that don't belong

Concerns / issues

Eitan's Comments

sound_drivers stack

• The Roadmap and Troubleshooting pages for the stack need to be created. Even if there's nothing much to say, the grayed-out links on the sidebar are confusing.
  • Done

sound_play package

• A link to external documentation on configuring SDL and ALSA/OSS might be helpful to give users a place to go. Although, people should really know how to figure that out for themselves... if you have a good resource you might as well link to it though. Actually, after seeing the "ConfiguringAndUsingSpeakers" tutorial, you could just link to that and perhaps link to external documentation from there.

  • I added a link from the main page to the tutorial, a link to the troubleshooting page in the tutorial, and a link to some alsa pages in the troubleshooting page. The alsa pages aren't that great or user friendly, so they are probably the last place I want to be sending the user. Part of the problem of getting alsa going is that there isn't a non-distro specific, up to date, not-crappy page that I know of.
• I would suggest adding a small section to the top of the "Command-line utilities section" explaining that the soundplay_node needs to be running for anything to work. Then provide an example of running the node from the command-line and the relevant xml to include in a launch file. I think that for less experienced users this would be helpful.
  • I have added a comment at the top of the "Command-line utilities section" saying that soundplay_node.py needs to be running. The comment includes a link to the tutorial that should allow the user to get the node going.

  • I have made the warning that the utilities print when there is nobody listening more explicit:

    Sound command issued, but no node is subscribed to the topic. Perhaps you forgot to run soundplay_node.py

  • I have added a section to the ROS API with a sample launch file (and will probably do this on all packages from now on).
• The doxygen looks just fine to me
  • Done (nothing to do)

ConfiguringAndUsingSpeakers tutorial

• Went through the tutorial and tried it out. Super easy for me.
  • Done (nothing to do)

Conclusion