From d078af41800bb5f8940879e83fef71001d2ddbee Mon Sep 17 00:00:00 2001
From: lowlighter <22963968+lowlighter@users.noreply.github.com>
Date: Sat, 15 Jan 2022 17:37:13 -0500
Subject: [PATCH] docs: update organization

---
 .../partials/documentation/organizations.md   | 38 +++++++++----------
 1 file changed, 17 insertions(+), 21 deletions(-)

diff --git a/.github/readme/partials/documentation/organizations.md b/.github/readme/partials/documentation/organizations.md
index 1e9174be..7281180f 100644
--- a/.github/readme/partials/documentation/organizations.md
+++ b/.github/readme/partials/documentation/organizations.md
@@ -1,41 +1,37 @@
-# 🏦 Organizations metrics
+# 🏦 Configure metrics for organizations
 
 While metrics targets mainly user accounts, it's possible to render metrics for organization accounts.
 
 ![Metrics (organization account)](https://github.com/lowlighter/metrics/blob/examples/metrics.organization.svg)
 
-## 💬 Metrics for organizations
+## *️⃣ Using *metrics* on organization
 
-Setup is the same as for user accounts, though you'll need to add `read:org` scope, **whether you're member of target organization or not**.
+Setup is the same as for user accounts, and a personal access token from an user account is required excepted that `read:org` scope must be enabled, **whether you are member of the target organization or not**.
 
 ![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png)
 
-You'll also need to set `user` option with your organization name.
-
-If you're encounting errors and your organization is using single sign-on, try to [authorize your personal token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).
-
-Most of plugins supported by user accounts will work with organization accounts, but note that rendering metrics for organizations consume way more APIs requests.
-
-To support private repositories, add full `repo` scope to your personal token.
-
-### ℹ️ Example workflow
+`user` option will need to be set to organization name instead.
 
+*Example: render metrics for `github` organization*
 ```yaml
 - uses: lowlighter/metrics@latest
   with:
-    # ... other options
-    token: ${{ secrets.METRICS_TOKEN }}          # A personal token from an user account with read:org scope
-    user: organization-name                      # Organization name
+    token: ${{ secrets.METRICS_TOKEN }}
+    user: github
 ```
 
-### 💬 Organizations memberships for user accounts
+> 💡 If your organization using single sign-on, you may need to [authorize your personal token access](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on)
 
-Only public memberships can be displayed by metrics by default.
-You can manage your membership visibility in the `People` tab of your organization:
+> 💡 Plugins supporting organizations account are labeled with `👥 Organizations`. Note that rendering consume way more API requests and huge organization may not actually be able to use a given plugin.
+
+> 💡 To support private repositories, add `repo` scope
+
+## *️⃣ Organizations memberships for user accounts
+
+By default, GitHub only display public memberships.
+Membership visibility canbe managed in the `People` tab of your organization.
 
 ![Publish organization membership](/.github/readme/imgs/setup_public_membership_org.png)
 
-For organization memberships, add `read:org` scope to your personal token.
-
-![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png)
+> ⚠️ Seeing your organization membership in your profile **does not** mean that it is visible from other users! You can check this by viewing your profile in an private browser window.