[Documentation] [TitleIndex] [WordIndex

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

Conclusion

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


2022-05-28 12:57