web_apps_core/Reviews/2010-01-18_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. The only interface we're supporting is use over the web, which should be self-documenting (I'm relying on use-case results for that)
3. No tutorials, but instructions to get going on the web interface should be enough.
4. No packages have APIs to review

5. The documentation is light, but works with the StackDocumentation guidelines. The only issue is inconsistent scoping to "pr2" instead of "the robot" for expected / compatible hardware.

6. All packages in the stack belong.

Concerns / issues

• Naming - these apps are both scoped strongly to the pr2, and the web_app_core also appears to be scoped strongly to the pr2. The name web_apps_core doesn't communicate what to expect inside nearly as well as e.g. "pr2_web_apps" or "pr2_core_web_apps". A similar criticism would apply to the individual packages within it. I don't know how big a deal this is - if this is a trivial change, I think it's probably worth it, but I don't want to trigger major changes with this comment.

• Stack Manifest change (trivial) This stack contains core web apps that are shipped with a robot. Should change to say This stack contains core web apps that are shipped with a PR2.

• Manifest change for teleop_ps3 - should scope to the PR2 instead of "the robot"
• Instructions for using it from Stack page (FIXED)
• Trac links to report a bug and request a feature are broken

Conclusion

I'm OK with this after:

• Stack manifest change
• ps3_joystick manifest change
• Trac links are fixed