Revise Asana integration UI text and docs

Edit UI and docs

app/models/project_services/asana_service.rb

@@ -3,6 +3,8 @@
 require 'asana'
 
 class AsanaService < Service
+  include ActionView::Helpers::UrlHelper
+
   prop_accessor :api_key, :restrict_to_branch
   validates :api_key, presence: true, if: :activated?
 
@@ -11,20 +13,12 @@ class AsanaService < Service
   end
 
   def description
-    s_('AsanaService|Asana - Teamwork without email')
+    s_('AsanaService|Add commit messages as comments to Asana tasks')
   end
 
   def help
-    'This service adds commit messages as comments to Asana tasks.
-Once enabled, commit messages are checked for Asana task URLs
-(for example, `https://app.asana.com/0/123456/987654`) or task IDs
-starting with # (for example, `#987654`). Every task ID found will
-get the commit comment added to it.
-
-You can also close a task with a message containing: `fix #123456`.
-
-You can create a Personal Access Token here:
-https://app.asana.com/0/developer-console'
+    docs_link = link_to _('Learn more.'), Rails.application.routes.url_helpers.help_page_url('user/project/integrations/asana'), target: '_blank', rel: 'noopener noreferrer'
+    s_('Add commit messages as comments to Asana tasks. %{docs_link}').html_safe % { docs_link: docs_link.html_safe }
   end
 
   def self.to_param
@@ -36,14 +30,17 @@ https://app.asana.com/0/developer-console'
       {
         type: 'text',
         name: 'api_key',
-        title: _('API key'),
-        placeholder: s_('AsanaService|User Personal Access Token. User must have access to task, all comments will be attributed to this user.'),
+        title: 'API key',
+        help: s_('AsanaService|User Personal Access Token. User must have access to the task. All comments are attributed to this user.'),
+        # Example Personal Access Token from Asana docs
+        placeholder: '0/68a9e79b868c6789e79a124c30b0',
         required: true
       },
       {
         type: 'text',
         name: 'restrict_to_branch',
-        placeholder: s_('AsanaService|Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches.')
+        title: 'Restrict to branch (optional)',
+        help: s_('AsanaService|Comma-separated list of branches to be automatically inspected. Leave blank to include all branches.')
       }
     ]
   end

changelogs/unreleased/300567-okr-integrations-asana-review-and-revise-settings-related-ui-text.yml

+---
+title: Review and revise Integrations/Asana UI text
+merge_request: 57362
+author:
+type: other

doc/api/services.md

@@ -68,14 +68,14 @@ Example response:
 
 ## Asana
 
-Asana - Teamwork without email
+Add commit messages as comments to Asana tasks.
+
+See also the [Asana service documentation](../user/project/integrations/asana.md).
 
 ### Create/Edit Asana service
 
 Set Asana service for a project.
 
-> This service adds commit messages as comments to Asana tasks. Once enabled, commit messages are checked for Asana task URLs (for example, `https://app.asana.com/0/123456/987654`) or task IDs starting with # (for example, `#987654`). Every task ID found gets the commit comment added to it. You can also close a task with a message containing: `fix #123456`. You can find your API Keys here: <https://developers.asana.com/docs/#authentication-basics>.
-
 ```plaintext
 PUT /projects/:id/services/asana
 ```
@@ -84,8 +84,8 @@ Parameters:
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `api_key` | string | true | User API token. User must have access to task, all comments are attributed to this user. |
-| `restrict_to_branch` | string | false | Comma-separated list of branches which are automatically inspected. Leave blank to include all branches. |
+| `api_key` | string | true | User API token. User must have access to task. All comments are attributed to this user. |
+| `restrict_to_branch` | string | false | Comma-separated list of branches to be are automatically inspected. Leave blank to include all branches. |
 | `push_events` | boolean | false | Enable notifications for push events |
 
 ### Delete Asana service

doc/user/project/integrations/asana.md

+---
+stage: Create
+group: Ecosystem
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Asana service **(FREE)**
+
+This service adds commit messages as comments to Asana tasks.
+Once enabled, commit messages are checked for Asana task URLs (for example,
+`https://app.asana.com/0/123456/987654`) or task IDs starting with `#`
+(for example, `#987654`). Every task ID found gets the commit comment added to it.
+
+You can also close a task with a message containing: `fix #123456`.
+You can use either of these words:
+
+- `fix`
+- `fixed`
+- `fixes`
+- `fixing`
+- `close`
+- `closes`
+- `closed`
+- `closing`
+
+See also the [Asana service API documentation](../../../api/services.md#asana).
+
+## Setup
+
+In Asana, create a Personal Access Token.
+[Learn about Personal Access Tokens in Asana](https://developers.asana.com/docs/personal-access-token).
+
+Complete these steps in GitLab:
+
+1. Go to the project you want to configure.
+1. Go to the [Integrations page](overview.md#accessing-integrations).
+1. Select **Asana**.
+1. Ensure that the **Active** toggle is enabled.
+1. Paste the token you generated in Asana.
+1. (Optional) To restrict this setting to specific branches, list them in the **Restrict to branch**
+   field, separated with commas.
+1. Select **Save changes** or optionally select **Test settings**.
+
+<!-- ## Troubleshooting -->

doc/user/project/integrations/overview.md

@@ -25,8 +25,7 @@ want to configure.
 Click on the service links to see further configuration instructions and details.
 
 | Service | Description | Service Hooks |
-| ------- | ----------- | ------------- |
-| Asana     | Asana - Teamwork without email | No |
+| Asana     | Add commit messages as comments to Asana tasks | No |
 | Assembla | Project Management Software (Source Commits Endpoint) | No |
 | [Atlassian Bamboo CI](bamboo.md) | A continuous integration and build server | Yes |
 | Buildkite | Continuous integration and deployments | Yes |

locale/gitlab.pot

@@ -1896,6 +1896,9 @@ msgstr ""
 msgid "Add comment to design"
 msgstr ""
 
+msgid "Add commit messages as comments to Asana tasks. %{docs_link}"
+msgstr ""
+
 msgid "Add deploy freeze"
 msgstr ""
 
@@ -4176,13 +4179,13 @@ msgstr ""
 msgid "AsanaService|%{user} pushed to branch %{branch} of %{project_name} ( %{commit_url} ):"
 msgstr ""
 
-msgid "AsanaService|Asana - Teamwork without email"
+msgid "AsanaService|Add commit messages as comments to Asana tasks"
 msgstr ""
 
-msgid "AsanaService|Comma-separated list of branches which will be automatically inspected. Leave blank to include all branches."
+msgid "AsanaService|Comma-separated list of branches to be automatically inspected. Leave blank to include all branches."
 msgstr ""
 
-msgid "AsanaService|User Personal Access Token. User must have access to task, all comments will be attributed to this user."
+msgid "AsanaService|User Personal Access Token. User must have access to the task. All comments are attributed to this user."
 msgstr ""
 
 msgid "Ascending"