[ros-users] [Discourse.ros.org] [Quality Assurance] ROS pkg quality metrics: analysing ROS wiki pages

[Tully Foote]

[quote="gavanderhoorn, post:8, topic:4442"]
One of the ideas is that prescribing structure (ie: freedom from choice) would lead to improved readability and usability of the wiki (this is already done with the Package Links box and the Package Header). As youre probably aware, structure helps as it allows visitors to form habits (ie: quickly assess state of something as its easy to compare to others).

An added benefit of prescribing structure is that it makes analysis easier/possible. And with analysis comes the possibility for gamification, which is something that appears to work well for/in other projects/contexts.
[/quote]

Indeed I completely agree that prescribing structure is highly valuable.

[quote="gavanderhoorn, post:8, topic:4442"]
Auto-generation would certainly help, but as I wrote above, enforcing some minimal content might be equally as effective.
[/quote]

My point is that all the things above that you call out as being valuable steps in that direction are actually already outside the wiki content. 
I misspoke that "the wiki" when I should have said "a wiki" or "wikis" designed to be edited without significant structure. To cite wikipedia on what a wiki is: 

"A wiki engine is a type of content management system, but it differs from most other such systems, including blog software, in that the content is created without any defined owner or leader, and wikis have little implicit structure, allowing structure to emerge according to the needs of the users." https://en.wikipedia.org/wiki/Wiki

And related to this the wiki content is not particularly machine readable and is definitely not stored in an accessible way. To "enforce" content in the wiki is both antithetical to the wiki design and also technically very difficult with the requirement that you will need to start doing things like parsing the wiki markup. And what do you do if it "fails" your enforcement check?

I think it would make more sense to extend the package header to include or enforce anything you want rather based on machine readable content in the code. This can range from a potential custom yaml definition of the node api, to doxygen comments (which are used by the documentation job, rendered in a standard way for users to view), package.xml (which is turned into the package header on the wiki), or anything else.

There's also significant issues with the wiki and versioning and getting out of sync with the content of the code. It is often better suited to having the structured content in the source not on the wiki.

We can add and extend the ROS documentation website by adding more structured content. We generally call that the ROS wiki, but actually the majority of the content is already outside of the wiki engine. And to continue scaling we will want to continue to encourage and find more ways to use structured data outside the wiki engine as it's specifically not designed for structured data.





---
[Visit Topic](https://discourse.ros.org/t/ros-pkg-quality-metrics-analysing-ros-wiki-pages/4442/9) or reply to this email to respond.