docs - clarify basic actions based on changes to how they work (#28873) (#28894)

Co-authored-by: Jeff Bruemmer <jeff.bruemmer@gmail.com>

docs/actions/basic.md

@@ -4,22 +4,22 @@ title: Basic actions
 
 # Basic actions
 
-Basic actions are premade [actions](./introduction.md) that do things that people typically want to do when interacting with a database.
+Basic actions are "implicit" [actions](./introduction.md) that do things that people typically want to do when interacting with a database: Create, Update, Delete. Basic actions auto-track the schema of the source table backing the model. By auto-track the schema, we mean that Metabase will create action forms for people to fill out that include all of the fields from the primary source table that underlies that model.
 
-Basic actions auto-track the schema of primary source table backing the model. By auto-track the schema, we mean that Metabase will create forms for people to fill out that include all of the fields in the model from the primary source table that underlies that model, and the action will update whenever you change the model. Basic actions are only available for models that include a single primary key.
+Basic actions are only available for models that "wrap" a single table in a database (so, no joins or custom columns in the model definition).
 
-Custom columns are also excluded because they are computed columns; if you want to change a custom column's values, you should update the values in the columns used to compute that column.
-
-If you only want to give people the option to update a subset of columns, you can write a [custom action](./custom.md).
+If you only want to give people the option to update a subset of columns, or update columns in multiple tables, you can write a [custom action](./custom.md).
 
 ## Creating basic actions
 
-Once actions are enabled, you can create basic actions on a new or existing [model](../data-modeling/models.md).
+Once actions are enabled, you can create basic actions on a new or existing [model](../data-modeling/models.md) that only wraps a single database table.
 
 1. Select a model and click on the **info** button, then click on **Model detail**.
 2. On the model detail page, click on the **Actions** tab.
 3. Click on the **...** next to the **New Action** and select **Create basic actions**.
 
+> If your model includes a join or a custom column, or otherwise doesn't map to a single raw table in your database, Metabase cannot create these basic actions.
+
 ## Basic action types
 
 ![Basic actions](./images/basic-actions.png)
@@ -30,23 +30,19 @@ Basic actions include:
 - [Delete](#delete)
 - [Create](#create)
 
-By default, none of the input fields are required for basic actions.
-
 ### Update
 
-The update action will present people with a form with editable fields for each column in the primary source table that's also included in the model. So if the model's source table has columns a, b, c, and d, but the model only includes columns a, b, and c, then the form will only show input fields for columns a, b, and c.
+The update action will present people with a form with editable fields for each column in the primary source table.
 
-When setting up an update action on a dashboard, you can either prompt the person to fill in a value for each field, or have a field automatically filled in via parameters (such as values set in dashboard filters).
+When setting up an Update action on a dashboard, you can either prompt the person to fill in a value for each field, or have a field automatically filled in via parameters (such as values set in dashboard filters).
 
 ### Delete
 
-The Delete action will create a form that prompts people for an ID, and will delete the record (row) in the underlying table that backs the model.
+The Delete action will create a form that prompts people for an ID, and will delete the record (row) corresponding to that ID in the underlying table that backs the model.
 
 ### Create
 
-The Create actions is the `INSERT INTO` action. The Create action will present a form with editable fields for each column in the primary source table that's also included in the model. So if the model's source table has columns a, b, c, and d, but the model only includes columns a, b, and c, then the form will only show input fields for columns a, b, and c.
-
-Once filled out, the action will insert the record into the primary table that underlies the model.
+The Create action is the `INSERT INTO` action. The Create action will present a form with editable fields for each column in the primary source table backing the model. Once filled out, the action will insert the record into the primary table that underlies the model.
 
 ## Basic actions on dashboards
 
@@ -54,7 +50,7 @@ When setting up actions on a dashboard, you can either prompt the person to fill
 
 ## Archiving basic actions
 
-Because basic actions are made of magic, you cannot archive them. You can just toggle them on or off. From the model detail page, next the **New action** button, click on the **...** menu and click **Disable basic actions**.
+Because basic actions are made of magic, you cannot archive them. You can just toggle them on or off. From the model detail page, next to the **New action** button, click on the **...** menu and click **Disable basic actions**.
 
 ## Further reading
 

docs/actions/custom.md

@@ -19,7 +19,7 @@ There are two ways to create a custom action:
 
 ## Custom action editor
 
-Here you can write your own code to create an action, like writing an action that would only update a subset of the columns in a model.
+Here you can write your own code to create an action, like writing an action that would only update a subset of the columns in a table.
 
 For example, you could write an action that would update the `plan` column for a record in the `Invoices` table in the Sample Database:
 
@@ -32,7 +32,7 @@ WHERE id = {{ id }}
 {% endraw %}
 ```
 
-The above code will create a form that prompts people to input updated values for the (required) `plan` field and optionally the `payment` field for a given record specified by `ID`. The code in brackets `[[ ]]` makes it optional: the enclosed statement will only run if someone inserts a value in the payment field.
+The above code will create a form that prompts people to input updated values for the (required) `plan` field and optionally the `payment` field for a given record specified by `ID`. The code in brackets `[[ ]]` makes the statement optional: the bracket-enclosed statement will only run if someone inserts a value in the payment field.
 
 ## Field types for action variables
 
@@ -77,7 +77,7 @@ From the model detail page, click on the **...** next to the action. Once in the
 
 ### Make public
 
-Creates a publicly shareable link to the action form.
+Creates a publicly shareable link to the action form. Anyone with access to that link can fill out the form and run the action. Useful for creating surveys.
 
 ![Public action form](./images/public-form.png)
 

docs/actions/introduction.md

@@ -4,7 +4,7 @@ title: Introduction to actions
 
 # Introduction to actions
 
-> For now, actions are only available for PostgreSQL and MySQL
+> For now, actions are only available for PostgreSQL, MySQL, and H2 
 
 ![Example action](./images/example-action.png)
 
@@ -20,6 +20,8 @@ Here are a few ideas for what you can do with actions:
 - Mark the customer you’re viewing in a dashboard as a VIP.
 - Let team members remove redundant data.
 
+Actions are associated with [models](../data-modeling/models.md), but actions operate on the raw tables that back those models (actions don't directly affect models).
+
 ## Enabling actions
 
 To enable actions for a database connection, admins should click on the gear icon in the upper right and navigate to **Admin settings** > **Databases**, then click on the database you want to create actions for. On the right side of the connection settings form, toggle the **Model actions** option. 
@@ -28,7 +30,7 @@ For actions to work, the database user account (the account you're using to conn
 
 ## Who can use actions
 
-Actions are associated with models, so you'll need to have created (or access to) at least one model before you can start using actions.
+Actions are associated with models, so you'll need to have created (or have access to) at least one model before you can start using actions.
 
 - **To create or edit an action**, a person must be in a group with Native query editing privileges for the relevant database.
 -  **To run an action**, all you need is view access to the action's model or dashboard (or a link to a public action).