docs: ✏️ improve UI actions plugin readme

src/plugins/ui_actions/README.asciidoc

@@ -1,14 +1,68 @@
 [[uiactions-plugin]]
 == UI Actions
 
-An API for:
-
-- creating custom functionality (`actions`)
-- creating custom user interaction events (`triggers`)
-- attaching and detaching `actions` to `triggers`.
-- emitting `trigger` events
-- executing `actions` attached to a given `trigger`.
-- exposing a context menu for the user to choose the appropriate action when there are multiple actions attached to a single trigger.
+UI Actions plugins provides API to manage *triggers* and *actions*.
+
+*Triggers* are like events that can be "triggered". For, example one such
+trigger is when somebody applies filters on dashboard.
+
+*Actions* are pieces of code that execute in response to a trigger. For example,
+to the dashboard filtering trigger multiple actions can be attached. Once a user
+filters on the dashboard all possible actions are displayed to the user in a
+popup menu and the user has to chose one.
+
+In general this plugin provides:
+
+- Creating custom functionality (actions).
+- Creating custom user interaction events (triggers).
+- Attaching and detaching actions to triggers.
+- Emitting trigger events.
+- Executing actions attached to a given trigger.
+- Exposing a context menu for the user to choose the appropriate action when there are multiple actions attached to a single trigger.
+
+=== Basic usage
+
+To get started, first you need to know a trigger you will attach your actions to.
+You can either pick an existing one, or register your own one:
+
+[source,typescript jsx]
+----
+plugins.uiActions.registerTrigger({
+  id: 'MY_APP_PIE_CHART_CLICK',
+  title: 'Pie chart click',
+  description: 'When user clicks on a pie chart slice.',
+});
+----
+
+Now, when user clicks on a pie slice you need to "trigger" your trigger and
+provide some context data:
+
+[source,typescript jsx]
+----
+plugins.uiActions.getTrigger('MY_APP_PIE_CHART_CLICK').exec({
+  /* Custom context data. */
+});
+----
+
+Finally, your code or developers from other plugins can register UI actions that
+listen for the above trigger and execute some code when the trigger is triggered.
+
+[source,typescript jsx]
+----
+plugins.uiActions.registerAction({
+  id: 'DO_SOMETHING',
+  isCompatible: async (context) => true,
+  execute: async (context) => {
+    // Do something.
+  },
+});
+plugins.uiActions.attachAction('MY_APP_PIE_CHART_CLICK', 'DO_SOMETHING');
+----
+
+Now your `DO_SOMETHING` action will automatically execute when `MY_APP_PIE_CHART_CLICK`
+trigger is triggered; or, if more than one compatible action, is attached to
+that trigger, user will be presented with a context menu popup to select one
+action to execute.
 
 === Examples