ROS/Reviews/2010-01-19_Doc_Review

Reviewer:

• kwc

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?
   • kwc: yes
2. Are all of these APIs documented?
   • kwc: yes
3. Do relevant usages have associated tutorials?
   • kwc: lots!

4. Have all Packages in the Stack been API reviewed?

   • kwc: yes

5. Does the Stack conform to the StackDocumentation guidelines?

6. Are there Packages in the Stack that don't belong

   • kwc: in the future, the ROS stack will need to be split into multiple components so that GUI-related dependencies do not contaminate stack. Also, in the long-term, thirdparty dependencies should be migrated to rosdeps. Other stacks, like rosbrowse and rosmanual have been removed.

Concerns / issues

1. kwc

• need to finish doc review on message_filters
• installation page continues to be a work-in-progress and will change with debian-based installation
• long-term: resurrect rosmanual to collect ROS-core documentation in a linear presentation
• long-term: improve documentation on implementing a client library

2. mwise

• make Names more prominent, people seem to struggle with this concept frequently and it shows in the documentation commonly

• Implementing Client Libraries needs to become more than notes

• the diagram in ROS/Technical Overview needs to be updated

• need better linking to the PyStyleGuide and CppStyleGuide

• DevelopersGuide has some empty code blocks that are meant to show examples but have no examples

• PackageDocumentation and StackDocumentation pages should parallel eachother more

• AutomatedTesting should link to UnitTesting

• StackReleaseProcess needs to updated

• In general it looks like more cohesive layout for the DevelopersGuide / QAProcess / rosbuild / UnitTesting need to be thought out and cleaned up to make sure that people can find the information they are looking for

Conclusion