Add a note about using raw data attributes as a prefered way

Author: bocharsky-bw

src/StimulusBundle/doc/index.rst

@@ -57,14 +57,27 @@ directory. In fact, you should have an example controller there already: ``hello
         }
     }
 
-Use the Twig functions from this bundle to activate your controllers:
+Then, activate the controller in your HTML:
+
+.. code-block:: html+twig
+
+    <div data-controller="hello">
+       ...
+    </div>
+
+Optionally, this bundle has a Twig function to render the attribute:
 
 .. code-block:: html+twig
 
     <div {{ stimulus_controller('hello') }}>
         ...
     </div>
 
+    <!-- would render -->
+    <div data-controller="hello">
+       ...
+    </div>
+
 That's it! Whenever this element appears on the page, the ``hello`` controller
 will activate.
 
@@ -159,6 +172,17 @@ Stimulus Twig Helpers
 This bundle adds 3 Twig functions/filters to help add Stimulus controllers,
 actions & targets in your templates.
 
+.. note::
+
+    Though this bundle provides these helpful Twig functions/filters, it's
+    recommended to use raw data attributes instead, as they're straightforward.
+
+.. tip::
+
+    If you use PhpStorm IDE - you may want to install
+    [Stimulus plugin](https://plugins.jetbrains.com/plugin/18940-stimulus)
+    to get nice auto-completion for the attributes.
+
 stimulus_controller
 ~~~~~~~~~~~~~~~~~~~
 
@@ -243,6 +267,11 @@ there's also a ``stimulus_controller`` filter:
         Hello
     </div>
 
+    <!-- would render -->
+    <div data-controller="chart other-controller" data-chart-name-value="Likes">
+        Hello
+    </div>
+
 You can also retrieve the generated attributes as an array, which can be helpful e.g. for forms:
 
 .. code-block:: twig