Instructions for doing a doc review
See DocReviewProcess for more instructions
- Does the documentation define the Users of the Stack, i.e. for the expected usages of the Stack, which APIs will users engage with?
- Are all of these APIs documented?
- Do relevant usages have associated tutorials?
Have all Packages in the Stack been API reviewed?
Does the Stack conform to the StackDocumentation guidelines?
- Are there Packages in the Stack that don't belong
Concerns / issues
- 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.
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)
- Went through the tutorial and tried it out. Super easy for me.
- Done (nothing to do)