[ros-users] ROS versioning & wiki structure

Sun Nov 23 03:04:44 UTC 2014

The poor visibility of the tutorials on package wikipages is an obstacle,
IMO— unless the main page specifically draws attention to the Tutorials
subpage, a lot of times it's not obvious they're even there, which can
erode the motivation to spend a lot of time on them.

A great first step would be a script that is run once sometime during the
beta phase of a new distro, which *stamps every single tutorial page on the
entire wiki with a warning box* that says, "Caution: Contents may have
settled during shipping! The following tutorial content has not been marked
as up to date for [ROS Jade]", and then stamp the toplevel package page
with a similar warning, "Caution: This package has [N] tutorial subpages
which have not yet been checked as being up-to-date for [ROS Jade]."

It's sort of graffiti, but it introduces a gamification element— for a
maintainer, you check over and update the tutorials, and then receive the
warm fuzzies of getting to remove the badge. From the user's perspective,
you have the confidence of "someone looked over this". There could even for
a python3wos-style dashboard which finds all the tutorial pages and gives
props to the updated ones.

More connected with the original post, I think what's most frustrating to
me is how the wiki tries to be a reference from the beginning of time. I
really wish the Version seesaw stopped at Groovy or even Hydro, rather than
going all the way back to freaking Electric. I get wanting to preserve the
historical record, but it's an extra burden when you're trying to update a
tutorial originally written in 2010, with widgets which want it to be
compatible with every version in between. Having permission to permanently
chop out information pertaining to pre-catkin, pre-Groovy would really
lower the barrier to community contribution on docs in general and
tutorials specifically.

M.

On 22 November 2014 at 19:59, Francis Belliveau <f.belliveau at comcast.net>
wrote:

> There is no question that the tutorials need to have some sort of version
> specific control.
> It is very frustrating to start working through a tutorial only to find
> that you are working with a ROS version older that the tutorial examples
> are designed for.  Then, after upgrading to a newer version of ROS, you get
> to find out that the page was not fully updated to match the newer version
> either.
>
> There no doubt that a “and-newer” macro is fraught with danger.  There is
> no way that anybody can ever guaranteed future compatibility.  Hindsight
> makes it easy to be sure that “and-older” will remain valid.
>
> On Nov 19, 2014, at 10:18 PM, Daniel Stonier <d.stonier at gmail.com> wrote:
>
> >
> > 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) 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
> >
> >
> > _______________________________________________
> > 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/20141122/b9f621cb/attachment.html>