Restructure significant part of the controller documentation

Signed-off-by: Christian Wolf <github@christianwolf.email>

developer_manual/basics/controllers.rst

@@ -393,6 +393,10 @@ A :doc:`template <front-end/templates>` can be rendered by returning a TemplateR
 
     }
 
+Showing a template is the only exception to the rule to :ref:`not disable CSRF checks <csrf_introduction>`:
+The user might type the URL directly (or use a browser bookmark or similar) to navigate to a HTML template.
+Therefore, usage of the ``#[NoCSRFRequired]`` attribute (see :ref:`below<controller_authentication>`) is acceptable in this context.
+
 Public page templates
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -434,6 +438,9 @@ A ``OCP\\AppFramework\\Http\\Template\\SimpleMenuAction`` will be a link with an
 developers can implement their own types of menu renderings by adding a custom
 class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface.
 
+As the public template is also some HTML template, the same argumentation as for :ref:`regular templates<controller_template>` regarding the CSRF checks hold true:
+The usage of ``#[NoCSRFRequired]`` for public pages is considered acceptable and is actually needed to visit the page without an active account.
+
 Data-based responses
 --------------------
 
@@ -513,6 +520,10 @@ Now your method will be reachable via ``<server>/ocs/v2.php/apps/<APPNAME>/api/v
 JSON
 ^^^^
 
+.. warning::
+    The usage of standard controller to access content data like JSON (no HTML) is considered legacy.
+    Better use :ref:`OCS <ocscontroller>` for this type of requests.
+
 Returning JSON is simple, just pass an array to a JSONResponse:
 
 .. code-block:: php
@@ -551,6 +562,11 @@ Because returning JSON is such a common task, there's even a shorter way to do t
 
 Why does this work? Because the dispatcher sees that the controller did not return a subclass of a Response and asks the controller to turn the value into a Response. That's where responders come in.
 
+.. deprecated:: 30
+
+    Usage of classical controllers for data transmission should be avoided. Use OCS instead.
+
+
 Handling errors
 ^^^^^^^^^^^^^^^