[ros-users] ROS versioning & wiki structure

[Edwards, Shaun M.]

All,

The developers and maintainers in ROS-I are working on our official Indigo release (we always lag the ROS releases).  A high priority for the team is to improve the documentation on the ROS wiki.  As we have several releases behind us, with many packages being actively updated/developed, I am worried that managing the complexity of a single wiki for all versions will become difficult.  When it comes to documenting multiple versions, we have two options:

1.       Use wiki macros to change content dynamically within a single wiki page.

2.       Create new version specific wiki pages (as sub-pages to the package wiki page) and then modify any content that needs to be updated.
Option 1 allows us to reuse common content.  This has been our approach, but I believe this is becoming complex as time(versions) goes on.
Option 2 makes multiple copies of pages, sometimes with little to no difference between them.  However, it is very robust since new modifications do not affect the other ROS versions.

I am leaning towards option 2.

Does anybody else have these problems?  If we start creating a bunch of wiki sub-pages, will this affect the wiki performance (negatively)?  It feels like the ROS approach of handling wiki versions at a package level is counter to most other software documentation (i.e. python https://docs.python.org/2/ & https://docs.python.org/2.6/ ) where versions are captured (and copied) at the root level.

Thanks,

Shaun Edwards
Senior Research Engineer
Manufacturing System Department


http://robotics.swri.org
http://rosindustrial.swri.org/
http://ros.swri.org<http://ros.swri.org/>
Join the ROS-Industrial Developers List<https://groups.google.com/group/swri-ros-pkg-dev/boxsubscribe>
Southwest Research Institute
210-522-3277

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20141119/92faec96/attachment.html>