microstrain_3dmgx2_imu/Reviews/Jan 7 2010_Doc_Review

Reviewer:

• Jeremy Leibs

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. If there are hardware dependencies of the Package, are these documented?
5. Is it clear to an outside user what the roadmap is for the Package?
6. Is it clear to an outside user what the stability is for the Package?
7. Are concepts introduced by the Package well illustrated?
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
9. Are any mathematical formulas in the Package not covered by papers properly documented?

Jeremy

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?
   • People that need to communicate with 3DM-GX2 IMU.
   • A picture would be fantastic.
   • People looking to talk to driver directly (programmatic API) may find this page. A pointer for them would be helpful. Also a mention of whether that API is intended to be stable or not.
   • Technically only receive a specific type of message from the IMU. No mention of how to get other message types.
2. Are all of these APIs documented?
   • No mention of programmatic API.
   • Should probably mention that the node adheres to the more general IMU API discussed on the stack page.
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?
   • Very simple tutorial. Should be sufficient for someone that knows what they want to do with the data.
4. If there are hardware dependencies of the Package, are these documented?
   • Device must adhere to the 3DM-GX2 protocol.
5. Is it clear to an outside user what the roadmap is for the Package?
   • Nothing mentioned. Could explicitly mention that nothing is planned in the near future aside from bug-fixes / support.
6. Is it clear to an outside user what the stability is for the Package?
   • API is listed as stable.
7. Are concepts introduced by the Package well illustrated?
   • No real concepts introduced.
8. Is the research related to the Package referenced properly? i.e. can users easily get to relevant papers?
   • N/A
9. Are any mathematical formulas in the Package not covered by papers properly documented?
   • N/A

For each launch file in a Package

1. Is it clear how to run that launch file?
   • One simple launch file that sets appropriate values for parameters.
2. Does the launch file start up with no errors when run correctly?
   • Not at first, but ERROR message was informative (and listed in troubleshooting guide)
3. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?
   • Yes

Concerns / issues

• A picture of a 3dm-gx2 would make the page look much more polished and official

• Short mention of programmatic API, even if only to say it is subject to change

• Mention of the fact that we only use 1 of the 3dm-gx2 protocol message types.

• Brief roadmap statement? Do we plan to add other message types in the future, or is this slated for bugfixes only for some time now.

Conclusion