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://rosindustrial.swri.org/
Join the ROS-Industrial Developers List
Southwest Research Institute
210-522-3277