rosbag/Reviews/2010-01-11_Doc_Review

Reviewer:

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?
2. Are all of these APIs documented?
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?
4. Is it clear to an outside user what the roadmap is for the Package?
5. Is it clear to an outside user what the stability is for the Package?
6. Are concepts introduced by the Package well illustrated?

Concerns / issues

kwc:

• this, especially, needs a roadmap page, as well as comments on stability

  • JL: Added

• I renamed ROS/LogFormat to Bags/Format, as it really is the bag format. Bag format page has a TODO on it, that should probably be deleted (or fixed).

  • JL: I had meant to do that and forgot -- thanks!

gjones:

• Given that this is a repackaging at this point I think it might make sense to put a small section about equivalence with the old rosrecord tools: i.e. rosplay = rosbag play. This could aid in migration. Furthermore, the rosrecord tutorials are still based on the old tools, but if there was an equivalence chart people could run the tutorials by replacing commands.

  • JL: I actually made a parallel rosbag tutorial with the new commands, but I agree a description of the tool mapping would be useful.

  • JL: Adding a section on mappings to old tools

• On that note, a link to the old tutorials would be useful, maybe with a brief explanation of how to run the tutorials with rosbag. My concern is that people will start searching for rosbag and get to a page without linked tutorials.

  • JL It has linked tutorials that are appropriate. Actually adding links to the old tutorials to point to the new ones.

tfield:

• Nothing to add to the above comments.

Conclusion