[ros-users] ROS versioning & wiki structure

[Dirk Thomas]

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.
>
>
>
> 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
>