web_apps_core/Reviews/2010-01-18_Doc_Review
Reviewer:
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?
- 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)
- No tutorials, but instructions to get going on the web interface should be enough.
- No packages have APIs to review
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.
- 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
