ROS Wiki 'landing' page of ind_robot_client missing 'node api' section

[gavanderhoorn]

The current wiki page of the industrial_robot_client package shows the typical content (intro, toc, overview), but then immediately 'goes deep' (ie Modification for Robot-Specific Needs).

I'd expect to find an overview of the node api there -- similar to the industrial_robot_simulator page -- but that information is under the 'this page' link.

Perhaps this could be reversed? Move the Node API to the landing page, and place the more in-depth information on a separate page.

[shaun-edwards]

The 'this page' link is not obvious. Let's go ahead and reverse them.

[JeremyZoss]

The original intent of the wiki layout was to reflect the fact that the industrial_robot_client is not a ROS node, but rather a library. It is similar to the simple_message or tf libraries.

My thought was that end users wouldn't ever look to the industrial_robot_client page for documentation on how the robot nodes work. These should be documented on the robot-specific pages, as that is where users will go to look first. Granted, these pages should all look very similar, except for vendor-specific extensions.

In my mind, the intended "user" of the industrial_robot_client library is a low-level developer writing robot-interface driver code. This developer would primarily be looking for how to adapt the client for use with a new robot platform. Thus the initial wiki page content.

The default behavior exposed by the client lib was relegated to a sub-page, because this theoretically only applies to robots that use the industrial_robot_client lib directly, with no robot-specific modifications. So far, none of the robots meets this standard. They all have some vendor-specific modifications that at least affect internal operations, if not also the ROS API.

To minimize wiki maintenance, I could see the value of linking vendor-specific usage pages back to the ROS API of the "vanilla" industrial_robot_client implementation, and only documenting vendor-specific deviations.

I don't know that the best way to address the confusion you've identified is to swap the implementation and usage pages. What's the "core" issue you're trying to address? Would that be better fixed by providing node-level documentation for the robot-specific packages that actually provide those nodes (fanuc_driver, abb_common, motoman_driver, etc.)?

[gavanderhoorn]

@JeremyZoss: that makes a lot of sense.

But since it is possible for a robot to use just the industrial_robot_specific nodes (see ros-industrial/fanuc#22 fi), I think we should at least make the link to the node API easier to find.

One option might be to refactor the node API into an include-able wiki page, which can then be referenced to by all the manufacturer-specific pages. I'd suggest to directly include this in the industrial_robot_client page as well, with your explanation included (and perhaps back-links to the mfg-specific packages, as you suggest). This should address your maintenance concerns.

[gavanderhoorn]

@shaun-edwards: I just noticed I've been assigned this bug, but am unsure if I'm actually the right person to do anything about this. The comments of @JeremyZoss make sense, so just swapping the Node API for the other content might not actually be the best thing to do.

[shaun-edwards]

@gavanderhoorn, OK. Let's keep this on the back burner until after the hydro release.

[gavanderhoorn]

Added: diff.