[ros-users] ROS versioning & wiki structure

Thu Nov 20 03:18:05 UTC 2014

On 20 November 2014 03:51, Dirk Thomas <dthomas at osrfoundation.org> wrote:

> Creating a lot more wiki pages will definitely impact the performance.
> MoinMoin does not use a database but the flat filesystem only and is
> not designed for 10k pages and more (which we have already exceeded).
>
> For a significant amount of wiki pages it is sufficient to have one
> single version only.
> Separating them for each ROS distro would be "overkill".
> Thats why imo a global branch of the whole wiki for each ROS distro is
> not useful.
>
> But in a lot of cases it makes sense to provide separate content.
> If option 1 or 2 fits your page better is imo completely up to the author.
> It mostly depends on how much the pages vary.
> Small changes: option 1, bigger changes: option2 - you can even mix
> and match these approach in a "single" page.
> Despite the performance impact mentioned above I would recommend to
> use the option which suites your pages better.
>
> I think the main limitation here is that you have to explicitly
> mention every ROS distro.
> That requires more maintenance than it should be.
> It would be great to extend these macros to also support version
> ranges like "groovy-and-lower" / "hydro-and-higher".
> That allows to integrate content changes for the ROS distro they
> occurred without requiring future maintenance.
> Implementing that feature is not too complex but would only require
> some develop time (see similar ticket
> https://github.com/ros-infrastructure/roswiki/issues/110).
>
> Cheers,
> - Dirk
>
> On Wed, Nov 19, 2014 at 8:59 AM, Edwards, Shaun M. <sedwards at swri.org>
> wrote:
> > 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.
> >
>

I think there's a distinct difference between the ros ecosystem and the
python scenario. The documented python ecosystem is finite and I suspect
everything in this set is checked when documenting a new version. The
documented ros ecocystem (i.e. roswiki) is not finite and missing checks.
You could of course copy existing documentation across by default, but I
believe that process should also have a human in the loop confirming that
yes, this documentation is still valid for the next rosdistro otherwise
you'll also copy alot of documentation which actually needs to be updated.
Working out whether a package's current documentation is no longer
applicable, or mostly true and worth digging around in is confusing and a
big deterrant for new ros users.

I use the wiki macros quite heavily. The rosdistro buttons that are now
inserted for a package's front page were a great idea. It makes it clear
what versions are available and if someone uses them it encourages people
to make sure the documentation is valid for each version. It also
highlights when no documentation has been officially checked/written for a
new distro (you'll get a black page if it hasn't). This feature is missing
for tutorials though - regardless of what rosdistro frontpage you are
looking at, you still go to just one tutorial index so I find myself
reconstructing a rosdistro based tutorial set (example
<http://wiki.ros.org/rocon_tools/Tutorials>) so I can construct rosdistro
based tutorial chains.

Once a package hasn't changed for two or three rosdistros, I try to switch
it back to a single documentation page for convenience.

The hydro and higher option sounds nice, but I wonder if that will create
problems too - it will encourage pages that will state that they're current
and valid, but are often not since no human has checked/validated it.

Daniel.

>
> >
> > Thanks,
> >
> >
> >
> > Shaun Edwards
> >
> > Senior Research Engineer
> >
> > Manufacturing System Department
> >
> >
> >
> >
> >
> > http://robotics.swri.org
> >
> > http://rosindustrial.swri.org/
> >
> > http://ros.swri.org
> >
> > Join the ROS-Industrial Developers List
> >
> > Southwest Research Institute
> >
> > 210-522-3277
> >
> >
> >
> >
> > _______________________________________________
> > ros-users mailing list
> > ros-users at lists.ros.org
> > http://lists.ros.org/mailman/listinfo/ros-users
> >
> _______________________________________________
> ros-users mailing list
> ros-users at lists.ros.org
> http://lists.ros.org/mailman/listinfo/ros-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ros.org/pipermail/ros-users/attachments/20141120/97951385/attachment.html>