I will describe the situation in a language-agnostic manner, but if you are interested in some specifics I will supply them at the bottom of the question.
I have a few open source libraries that have their documentation hosted by the the same service that hosts the packages for downloading. This hosting platform is going through some major changes, and one of those changes is that they are dropping support for hosting documentation and are advising users to use ReadTheDocs instead. In itself this is not an issue, but here are some facts that complicate matters:
- Uploads to the old documentation hosting platform have been disabled
- Automatic redirects to the new hosting service are not possible (both because we cannot upload our own and because the service does not support it)
- Old documentation currently on the old hosting platform can be deleted
This has created the following situation:
- The old documentation is now out of date because I have released new versions since uploads have been disabled.
- Any link on a website out of my control to the old documentation will go dead.
- 3 out of 5 of the top Google hits for my projects point to the old documentation hosting platform, so I am not excited about deleting the old documentation.
- As a test, a few weeks ago I deleted the old documentation for a less-used library, and for this package some of the top hits point to ReadTheDocs, but there are also still links to the old documentation.
I was thinking of adding a conspicuous note at the top of the README on the GitHub page that documentation hosting has been changed, but that does not seem like enough.
Should I bite the bullet and delete the old documentation and hope that the internet will "heal itself" with time? Or is there a better solution to take that will lead to a smoother transition for documentation?
For those interested, the ecosystem here is Python and the hosting platform that is reaching end-of-life is pythonhosted.org. Removing documentation hosting has been part of a roadmap for some time, but it seems that only #1 and #5 of the roadmap were actually implemented. This has caused issues where people such as myself want to make redirects but cannot (see here or here for relevant GitHub issues).