From 34203e9a0756fc1014139bf2ae082b37ee9212ca Mon Sep 17 00:00:00 2001
From: lowlighter <22963968+lowlighter@users.noreply.github.com>
Date: Sat, 15 Jan 2022 22:36:33 -0500
Subject: [PATCH] doc(plugins/followup): update

---
 source/plugins/followup/README.md    | 61 +++++++++++++++++-----------
 source/plugins/followup/metadata.yml | 21 ++++++----
 2 files changed, 51 insertions(+), 31 deletions(-)

diff --git a/source/plugins/followup/README.md b/source/plugins/followup/README.md
index 22817edb..f732720a 100644
--- a/source/plugins/followup/README.md
+++ b/source/plugins/followup/README.md
@@ -1,23 +1,30 @@
-### 🎟️ Follow-up of issues and pull requests
-
-The *followup* plugin displays the ratio of open/closed issues and the ratio of open/merged pull requests across all your repositories, which shows if they're well-maintained or not.
-
+<!--header-->
 <table>
-  <td align="center">
-    <details open><summary>Indepth analysis</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.indepth.svg">
-    </details>
-    <details><summary>Created on an user's repositories</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.svg">
-    </details>
-    <details><summary>Created by an user</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.user.svg">
-    </details>
-    <img width="900" height="1" alt="">
-  </td>
+  <tr><th colspan="2"><h3>🎟️ Follow-up of issues and pull requests</h3></th></tr>
+  <tr><td colspan="2" align="center"><p>This plugin displays the ratio of open/closed issues and the ratio of open/merged pull requests across all your repositories.</p>
+</td></tr>
+  <tr>
+    <th rowspan="3">Supported features<br><sub><a href="metadata.yml">→ Full specification</a></sub></th>
+    <td><a href="/source/templates/classic"><code>📗 Classic template</code></a> <a href="/source/templates/repository"><code>📘 Repository template</code></a></td>
+  </tr>
+  <tr>
+    <td><code>👤 Users</code> <code>👥 Organizations</code> <code>📓 Repositories</code></td>
+  </tr>
+  <tr>
+    <td><code>🔑 (scopeless)</code> <code>read:org (optional)</code> <code>read:user (optional)</code> <code>repo (optional)</code></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center">
+      <details open><summary>Indepth analysis</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.indepth.svg" alt=""></img></details>
+      <details><summary>Created on an user's repositories</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.svg" alt=""></img></details>
+      <details><summary>Created by an user</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.user.svg" alt=""></img></details>
+      <img width="900" height="1" alt="">
+    </td>
+  </tr>
 </table>
+<!--/header-->
 
-#### ➡️ Available options
+## ➡️ Available options
 
 <!--options-->
 <table>
@@ -26,7 +33,7 @@ The *followup* plugin displays the ratio of open/closed issues and the ratio of
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_followup</code></td>
-    <td rowspan="2"><p>Display follow-up of repositories issues and pull requests</p>
+    <td rowspan="2"><p>Enable followup plugin</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -36,7 +43,11 @@ The *followup* plugin displays the ratio of open/closed issues and the ratio of
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_followup_sections</code></td>
-    <td rowspan="2"><p>Sections to display</p>
+    <td rowspan="2"><p>Displayed sections</p>
+<ul>
+<li><code>repositories</code>: overall status of issues and pull requests on your repositories</li>
+<li><code>user</code>: overall status of issues and pull requests you have created on GitHub</li>
+</ul>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -48,7 +59,7 @@ The *followup* plugin displays the ratio of open/closed issues and the ratio of
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_followup_indepth</code></td>
-    <td rowspan="2"><p>Indepth follow-up processing</p>
+    <td rowspan="2"><p>Indepth analysis</p>
 <img width="900" height="1" alt=""></td>
   </tr>
   <tr>
@@ -60,9 +71,13 @@ The *followup* plugin displays the ratio of open/closed issues and the ratio of
 </table>
 <!--/options-->
 
-*[→ Full specification](metadata.yml)*
+## 🔎 `indepth` mode
 
-#### ℹ️ Examples workflows
+The `plugin_followup_indepth` option collects additional stats to differentiate issues and pull requests opened by maintainers and users.
+
+It helps knowing whether repositories are also maintained by other users and give an overall health status of repositories.
+
+## ℹ️ Examples workflows
 
 <!--examples-->
 ```yaml
@@ -97,4 +112,4 @@ with:
   plugin_followup_indepth: 'yes'
 
 ```
-<!--/examples-->
\ No newline at end of file
+<!--/examples-->
diff --git a/source/plugins/followup/metadata.yml b/source/plugins/followup/metadata.yml
index ded71d96..a89bd37a 100644
--- a/source/plugins/followup/metadata.yml
+++ b/source/plugins/followup/metadata.yml
@@ -1,5 +1,10 @@
 name: "🎟️ Follow-up of issues and pull requests"
 category: github
+description: This plugin displays the ratio of open/closed issues and the ratio of open/merged pull requests across all your repositories.
+examples:
+  +indepth analysis: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.indepth.svg
+  created on an user's repositories: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.svg
+  created by an user: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.followup.user.svg
 index: 7
 supports:
   - user
@@ -9,25 +14,25 @@ scopes:
   - public_access
 inputs:
 
-  # Enable or disable plugin
   plugin_followup:
-    description: Display follow-up of repositories issues and pull requests
+    description: Enable followup plugin
     type: boolean
     default: no
 
-  # Sections to display
   plugin_followup_sections:
-    description: Sections to display
+    description: |
+      Displayed sections
+      - `repositories`: overall status of issues and pull requests on your repositories
+      - `user`: overall status of issues and pull requests you have created on GitHub
     type: array
     format: comma-separated
     default: repositories
     values:
-      - repositories # Overall status of issues and pull requests on your repositories
-      - user         # Overall status of issues and pull requests you have created on GitHub
+      - repositories
+      - user
 
-  # Compute issues and pull requests per repositories with special highlighting for maintainers and specified users
   plugin_followup_indepth:
-    description: Indepth follow-up processing
+    description: Indepth analysis
     type: boolean
     default: no
     extras: yes