rosdoc/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, users of rosdoc are expected to interact with it through the command line tool and configuration files
2. Are all of these APIs documented?
   • Yes, in addition to examples on the wiki page, the API page has more complete documentation
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?
   • No, there are no tutorials, though there are examples presented on the main page. Some of these could get pulled out into more complete tutorials. The main candidate for this would probably be a tutorial built around the roslib example manifest, possibly with additional functionality. Another possibility might be a tutorial on setting up an external repository to be documented on ros.org, although I'm not sure what state that functionality is in.
4. Is it clear to an outside user what the roadmap is for the Package?
   • No, a section should be added at the bottom giving roadmap and stability information.
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?
   • Yes, there are a number of concrete examples presented for most concepts.

Concerns / issues

• In API doc, 'make clean && make upload-local' is not entirely clear. Are these specialized make targets which are designed for ros.org, or could they be useful for someone else? Does everything run at "compile time", without need for a separate invocation of rosdoc?

  • kwc: I removed the doxygen mainpage documentation and replaced with with Epydoc. The essential parts I pulled back into the wiki page.

Conclusion

• Depending on the intended audience you may want to push one or another use case to slightly greater prominence, but the basic information is there and well presented. For example, the encouragement to regularly run rosdoc locally is snuck into the bottom of section 4 where it is easily skipped, but for most people it may actually be the most relevant information. Also, if it is intended that rosdoc be usable for repository maintainers outside of willow the mechanism for this is not entirely clear to me.

kwc: I inserted a sentence near the top to encourage its use, but I agree there is a tension between rosdoc's automatic role versus it being a local tool. I'll think about a tutorial in the future, but I think the tool in general needs to be improved before that.

Doc reviewed