[ros-users] ROS versioning & wiki structure

Mon Nov 24 08:37:55 UTC 2014

+1 to remove non catkin-based information to an old wiki reference.

In my opinion, maintaining a repo and the documentation in two different
sites is a bit confusing. One often makes changes to the repository without
remembering how the roswiki entry was done, thus breaking the completeness
or correctness of it. As most of us are developing on GitHub, would it make
sense to have a document in each of our repositories "*something.roswiki"* so
that the documentation generator pastes it into the roswiki? Therefore, if
any user loses conectivity but has the package cloned from git, the
documentation is still available for him and also the maintenance of a
package is easier.
And, with these changes done, the tutorial work of a package could be
easily tracked using PRs and forks.

Miquel Massot

miquel.massot at gmail.com    <https://github.com/miquelmassot>

2014-11-23 22:13 GMT+01:00 Tully Foote <tfoote at osrfoundation.org>:

> Hi Mike,
>
> Here's a dump of the last months wiki page views.
> https://docs.google.com/spreadsheet/pub?key=0AjNmzxy4pVGMdHBzWDdHbm01V1pxWl91azR0TVJJV0E&output=ods
>
> The edit data is a lot harder to come by and less informative as it can
> not distinguish typos vs substantive review.
>
> Also if we're going to be reviewing pages, it probably makes sense to
> focus on the high traffic pages regardless of their tutorial status.
>
> Tully
>
> On Sun, Nov 23, 2014 at 12:16 PM, Mike Purvis <
> mpurvis at clearpathrobotics.com> wrote:
>
>> An interesting starting point here might just be some basic analytics to
>> understand the scope of the work.
>>
>> For example, having a list of all the tutorials sorted by traffic and
>> marked by last edit date would help focus community efforts. Like, "hey, if
>> you have a few hours to contribute to ROS, pick a high-traffic tutorial off
>> this list, and run through it to make sure it's still solid."
>>
>> If the raw traffic data for the wiki can be made public by OSRF, it's
>> possible myself or someone else could take this on at some point.
>>
>> On 23 November 2014 at 13:36, Dirk Thomas <dthomas at osrfoundation.org>
>> wrote:
>>
>>> While MoinMoin is not a great piece of technology the current wiki does
>>> provide us with several options:
>>>
>>> * having a single page and mention in the content for which ROS versions
>>> it has been confirmed to work
>>> * using the distro specific tabs to make minor adjustments for each ROS
>>> version
>>> * generating subpages for each specific ROS version to completely
>>> separate the content
>>>
>>> Generally I don't think that enforcing a specific approach for all pages
>>> makes sense.
>>> The "best" choice basically comes down to:
>>>
>>> * how much the content changes with each ROS version and
>>> * personal preference of the people maintaining the content
>>>
>>> Imo the major reason why the tutorials are not in a better shape is not
>>> a technological one.
>>> It simply takes **a lot** of effort to maintain them - also because we
>>> have so many of them (which is a great thing).
>>> And this maintenance work is done by a very small group of people.
>>>
>>> While it makes sense to consider enhancements to the wiki macros etc. i
>>> don't think that they will ever on their own "solve" the problem.
>>> We must encourage way more people to (write / ) maintain / review
>>> tutorials in order to spread the load and increase the coverage.
>>> (May be a technological enhancement which enables gamification might
>>> help to motivate more people to contribute.)
>>>
>>> - Dirk
>>>
>>> PS: Please also keep in mind that whatever change you propose must be
>>> implemented by someone.
>>> And if that change requires more maintenance of the wiki page content we
>>> need to have people actually doing that.
>>> So as good as it sounds to review each and every tutorial for a new ROS
>>> version I have a hard time believing that it is a realistic approach.
>>>
>>> On Sun, Nov 23, 2014 at 7:55 AM, Paul Bouchier <bouchier at classicnet.net>
>>> wrote:
>>>
>>>>  +1 for the idea of relegating old content to a history museum to
>>>> reduce maintenance.
>>>>
>>>> There can be other transitions in a package's life which change it so
>>>> dramatically that it's not worth maintaining the previous content. However,
>>>> the previous version is still there - in the version history.  Perhaps
>>>> there could be a  macro that let's an author refer to a history tag and
>>>> display a message something like "The version of this page prior to <XYZ>
>>>> his <here>, where <XYZ> could be "catkin" or "groovy" or "API version 2.0"
>>>> or "new-sensor-version" etc. etc. This could work for tutorial pages too.
>>>>
>>>> Paul Bouchier
>>>>
>>>>
>>>> On 11/22/2014 08:24 PM, Rud Merriam wrote:
>>>>
>>>> As someone new to ROS I find it very frustrating to have the pre-catkin
>>>> documentation in the Wiki.
>>>>
>>>> I would suggest you quickly move the pre-catkin material to a separate
>>>> Wiki for those still using those versions. Then begin a rolling update
>>>> system for new releases. You might keep three release in the main Wiki
>>>> while rolling previous releases into a historical Wiki separate from the
>>>> pre-catkin Wiki. That might entail too much work, I realize. Maybe a
>>>> diff/merge through a version control system would work? I suggest that
>>>> anyone working with versions 3 years out of date probably can figure out
>>>> the documentation even if it is not perfect.
>>>>
>>>>
>>>> - 73 -
>>>>
>>>> * Rud Merriam K5RUD *
>>>> * Mystic Lake Software <http://mysticlakesoftware.com/> *
>>>>
>>>>
>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> ros-users mailing listros-users at lists.ros.orghttp://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
>>
>>
>
> _______________________________________________
> 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/20141124/136641ad/attachment.html>