I’d like to post a request-for-comments for the following PR against
Our very active member @max-krichenbauer has submitted this PR following a suggestion I made to the SQWG some time ago to see whether we could improve the situation regarding outdated content on the ROS wiki.
This suggestion was based on my personal experience with questions on ROS Answers posted by (new) users about unclear or incomplete (or sometimes even incorrect) instructions or information on ROS wiki pages, combined with the results of one of the earlier community-oriented studies performed in the ROSIN project (which showed that newcomers are particularly frustrated by the fact that it’s almost impossible to figure out whether a source of information is still relevant (be it a wiki page, tutorial or blog post)).
As a first approach, the PR implements an extension to the wiki which shows a notice at the top of the wiki page whenever the
last-edited property is older than some configurable threshold. Like so:
This is of course just an example.
I am pretty sure there are numerous pages which haven’t been touched for years but their content is still as valid / relevant / up-to-date as it needs to be. And also some pages might have recently been touched for minor changes but still contain outdated content
The main problem is of course the fact that to do this properly (ie: determine whether content is still relevant), understanding of both the content and the state-of-the-art would be necessary (something not very easily captured in 25 lines of Python). In essence, this would require humans to be part of the process.
While it would be great if we could all keep the ROS wiki up-to-date, the past years have shown this to not happen. Including humans all the time seems infeasible.
The idea however of this simple PR would be to add at least some indication of potentially outdated information, under the assumption that with a project as active as ROS, the fact that a wiki page hasn’t been edited in (say) 2 years does indeed mean there is a relatively high chance that at least some things may not work any more as they are described or documented.
Such a notice does of course not really solve the problem (as for that a human would need to update the page and correct any issues), but instead of not showing anything (by which we implicitly state the page as-is documents the current state of things and everything should just work), we at least acknowledge the fact that things could have changed and we warn the reader that he should be aware of this.
I’d like to ask people here to comment on the PR and voice their opinions.
It would be great if we could figure out some solution, especially also because of the ROS 1 -> ROS 2 migration, which will probably mean we’ll see more-and-more content becoming stale in the near future.