I am glad to tell that I finally managed to solve an issue that caused confusion for years. Someone had cloned and published the rsyslog documentation at readthedocs. Unfortunately, it was not maintained afterwards and also looked like an official rsyslog doc. That added a lot to the “rsyslog’s doc is bad and inconsistent” feel inside the community. This could now be resolved, and current, official doc is now available at readthedocs. I am very happy and glad for readthedocs staff members who helped us to finally resolve the issue.
AI exposes the Problem even more
The problem worsened as AI grew. readthedocs is a well-respected doc site with a lot of trustworthiness in SEO and AI ingestion. That made the AI agents believe the doc there would be almost as good as on rsyslog.com. As it was a 2016 snapshot, this introduced a lot of inconsistency between the real state and what it claimed, opening a real big problem in regard to AI hallucination and simple AI picking the wrong format.
I tried several times in the past to work with the original submitter, but to no avail. I think I also tried at least once to contact readthedocs, but I am sure I did it wrongly. At that time I did not have the insight and was simply left frustrated. With the rise of AI, I saw an even stronger need to correct the issue.
Due to my past experience, I now used AI help to understand how to contact readthedocs and that told me how to do it right. That said, all worked swiftly, and the support at readthedocs was very professional and solved the issue according to their policies. I have now control over the project and it displays the current rsyslog documentation (yay!).
That said, we will keep the rsyslog doc up at readthedocs as well. I think there are some folks who have become used to read it over there, and there may be other folks who simply prefer the site. As we can now keep the version current, and so it is great to have another vary capable mirror in place.
Some Outdated Doc Problems remain
We still have some minor issues, e.g. on readthedocs there is published v5 rsyslog doc, which of course is hopelessly outdated. I can understand the will to provide v5 specific info, even though I wonder if really someone still runs a system 10+ years outdated. I will try to contact it’s maintainer to check if he will accept a small update so that any page tells it is outdated and no longer relevant to current rsyslog.
Note that this of course is not only a readthedocs issue – outdated doc and code snippets are all over the Internet and we need to fight this in order to streamline the user experience. Naturally, I everyone does this for good reason, and we appreciate the work people have done over the years to help rsyslog users. So this “fight” is one of decent demotion (by better doc and spider hints) as well as identifying top ranking pages and trying to help their owners to update them.
Note that even my blog holds outdated snippets. We currently evaluate an automated method to tell this spiders.
Quick Wrap-Up
But I am sure that the now-correct readthedocs “rsyslog” project is a huge step forward into better user experience and AI ingestion.