rosout/Reviews/2010-01-12_Doc_Review

Reviewer: Ethan

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?
   • Yes, C++ users are directed to rosconsole, python users to rospy logging, and those trying to view logging messages to rxconsole
2. Are all of these APIs documented?
   • Yes, though since none of them are actually part of the rosout package I have not doc-reviewed them
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?
   • The tutorials and troubleshooting links are both dead. Should a page be created which links to nothing? I don't think there are any package level tutorials required.
4. Is it clear to an outside user what the roadmap is for the Package?
   • No, stability and roadmap should be specified somewhere, even if it's just to say that the rosconsole elements are stable and unlikely to change any time soon
5. Is it clear to an outside user what the stability is for the Package?
   • No, see above.
6. Are concepts introduced by the Package well illustrated?
   • Most of the significant concepts are covered by the linked pages. The only concept that could use a little more explanation is the difference between rosout_agg and rosout. Perhaps the aggregation mechanism could be expanded upon in a sentence or two.

Concerns / issues

• I'm assuming that rosconsole/roscpp/rospy/rxconsole are receiving separate doc reviews, including for the logging portion, if this is not the case let me know and I'll go back and review the relevant pages

• The Log.msg section does not really make sense to me. For one thing it appears to be out of date. For another the link already provided to doc/api/roslib/html/msg/Log.html seems like all that's really needed.

Conclusion

• Clean up (update or probably remove) the log.msg section, add a stability/roadmap section, and add a sentence or two about the aggregated feed