Apply suggestions from code review

Co-authored-by: Steve Piercy <[email protected]>

Author: jensens

docs/backend/portal-actions.md

@@ -24,52 +24,58 @@ Portal actions are typically displayed in the site's navigation menu or toolbar
 Portal actions are managed using the {guilabel}`Portal Actions` control panel in Plone.
 This control panel allows you to add, edit, and delete actions, as well as organize them into categories and control where they are available on your site.
 
+```{note}
+We use the terms "Portal actions" and "Actions" in this documentation to mean the same thing.
+```
+
 ## Anatomy of a Portal action
 
 A portal action in Plone consists of a few settings, including the category, title, description, URL, and control parameters.
 
-The action title is the text that is displayed for the action in the site's navigation menu or toolbar.
+The action {guilabel}`Title` is the text that is displayed for the action in the site's navigation menu or toolbar.
 This text should be descriptive and indicate what the action does.
-The description is used as an additional text shown when hovering over the link.
-The title and description can be translated using the translation system of Plone.
-Therefore the i18n domain can be set here.
+The {guilabel}`Description` is used as an additional text shown when hovering over the link.
+The {guilabel}`Title` and {guilabel}`Description` can be translated using the translation system of Plone.
+Therefore the {guilabel}`I18n domain` can be set here.
 
-The Action URL is the address of the page or feature that the action will access when it is clicked.
+The {guilabel}`Action URL` is the address of the page or feature that the action will access when it is clicked.
 This can be an internal page on your site or an external page on another website.
 
-The "Condition" controls whether to show the action or not.
+The {guilabel}`Condition` controls whether to show the action or not.
 
-You can use expressions in the URL of an action to make the action more dynamic and flexible. Expressions are also used for the "Condition".
+You can use expressions in the URL of an action to make the action more dynamic and flexible.
+Expressions are also used for the {guilabel}`Condition`.
 
-The permissions chosen also control the visibility of an action.
+The {guilabel}`Permissions` chosen also control the visibility of an action.
 
-Visibility can be used to hide actions.
+The {guilabel}`Visible?` setting can be used to show or hide actions.
 This can be handy to disable default actions or temporarily disable actions.
 
-The "Position" is used to order action within their category and is numbered starting with "1".
+The {guilabel}`Position` setting is used to order actions within their category, and is numbered starting with `1`.
 
 Together, these components make up a portal action in Plone.
 
-You can use the "Portal Actions" control panel to manage and organize your site's actions.
+You can use the {guilabel}`Portal actions` control panel to manage and organize your site's actions.
 
 ## Action categories
 
-Several different action categories are used for different purposes.
+Several action categories are used for different purposes.
 These categories include:
 
 Object Actions
-: `Actions that are available when viewing a specific content item.`
+: Actions that are available when viewing a specific content item.
 
 Object Buttons
-: `Actions that are displayed as buttons when viewing a specific content item.`
+: Actions that are displayed as buttons when viewing a specific content item.
+
 Portal Tabs
-: `Actions that are displayed as tabs on the top of the page.`
+: Actions that are displayed as tabs on the top of the page.
 
 Site Actions
-: `Actions that are available on every page of your site`
+: Actions that are available on every page of your site.
 
 User Actions
-: `Actions that are available to users when they are logged in to your site`
+: Actions that are available to users when they are logged in to your site.
 
 Each of these action categories serves a different purpose and is intended for use in specific areas of the site.
 For example, object actions are intended for actions that are specific to a particular content item, while site actions are intended for actions that are available on every page of your site.
@@ -86,15 +92,24 @@ See issue [Backend > missing chapter Expressions needs content](https://github.c
 
 ## Adding or editing portal actions
 
-To add or edit portal actions, you can use the Portal Actions control panel.
-To access this, log in to your Plone site as a user with the appropriate permissions, and then go to the {guilabel}`Site Setup` page.
-From there, click on the {guilabel}`Portal Actions` link in the {guilabel}`Plone Configuration` section.
+To add or edit portal actions, you can use the {guilabel}`Portal actions` control panel.
+To access this, log in to your Plone site as a user with the appropriate permissions.
+Then select the menu item {menuselection}`[username] > Site Setup`.
+From there, click on the {guilabel}`Actions` link in the {guilabel}`General` section.
+You can also select {menuselection}`General > Actions` from the Site Setup or any other control panel.
+
+Once you are on the {guilabel}`Portal actions` control panel, you will see a list of all the existing portal actions for your site.
+To inspect or edit an existing action's settings, click its {guilabel}`Edit` button.
+
+[insert screenshot from Steve here]
 
-Once you are on the "Actions" control panel, you will see a list of all the existing portal actions for your site.
 To add a new action, click on the {guilabel}`Add new action` button at the top of the page.
-This will open a form where you can enter the details for your new action, such as the action name, URL, and any additional parameters.
+This will open a form where you can enter select its category and enter an arbitrary ID.
+Click the {guilabel}`Add` button to add the action.
+The new action should now appear in the actions listing under the selected category.
+You can now edit its settings by clicking its {guilabel}`Edit` button.
 
-To edit an existing action, click on the action name in the list to open the action's details page.
+To edit an existing action's settings, click its {guilabel}`Edit` button.
 From there, you can edit the action's properties, such as the name, URL, and parameters.
 
 It's important to note that the ability to add or edit portal actions is only available to users with the appropriate permissions.