Deprecated documentation details

[jsduenass]

When Reading about the deprecated documentation. It mentions two sources of documentation that are deprecated ROS 2 Docs and ROS 2 Design. However, expanding about how the decision of deprecating these sources of documentation were taken by for example referencing the documents where the decisions were made.

The documentation is currently referencing these deprecated sources is this an issue?

ROS 2 Docs url is referenced in:

• source/Concepts/About-Internal-Interfaces.rst
• source/Concepts/About-Internal-Interfaces.rst
• source/Concepts/About-ROS-2-Client-Libraries.rst
• source/Tutorials/Intermediate/Writing-an-Action-Server-Client/Py.rst

ROS 2 Design url is referenced in:

• source/Concepts/About-Build-System.rst:
• source/Tutorials/Intermediate/Creating-an-Action.rst

Knowing more about the depreaction could help with #3078

[clalancette]

So I think there are 2 different things to do here:

1. On http://docs.ros.org/en/rolling/ , describe why the deprecated places have been deprecated, and what their replacements are.
2. Rewrite some of the references to the deprecated documentation so that they point to the new documentation.

That said, we don't have plans to work on this right now. @kscottz FYI.

[kscottz]

I don't know if I have the full context here, but it would seem to me that we might be better off removing links to deprecated resources. We don't necessarily need to explain deprecated resources other than saying, "these are no longer up to date." docs.ros2.org and design.ros2.org are before my time, and I am not sure how to edit them, but having a "This resource is deprecated" banner at the top would certainly save users a lot of grief.

We're fighting an up-hill battle with search engines preferring to point to older, more referenced works, over newer, more up-to-date works. The more we can de-reference the out of date works, the better. @jsduenass the pointers you provided are rather helpful, thanks! I don't know if I can necessarily replace all of them with new resources, but I can take a minute tomorrow to remove them entirely as they are out of date and confusing.

[clalancette]

I don't know if I have the full context here, but it would seem to me that we might be better off removing links to deprecated resources. We don't necessarily need to explain deprecated resources other than saying, "these are no longer up to date." docs.ros2.org and design.ros2.org are before my time, and I am not sure how to edit them, but having a "This resource is deprecated" banner at the top would certainly save users a lot of grief.

So docs.ros2.org is still hosting the (only) documentation for Foxy; we should leave that online until Foxy goes EOL later this year. After that, we can shut it down completely.

design.ros2.org is harder. It still holds quite a number of our active design documents, so it still has utility. But the long-term goal with it is to move everything out of there and either host it here, or in REPs. It is just a lot of work to get there, and we haven't had time to do it.

I'm not sure where that leaves us, to be honest.