From 1f74d6599f4a5e89a20d3c99aab4e6a70f7bda0f Mon Sep 17 00:00:00 2001
From: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Date: Tue, 26 Dec 2023 02:30:13 +0000
Subject: [PATCH] Move usage instructions above the fold

---
 README.rst | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/README.rst b/README.rst
index 1111901..404144a 100644
--- a/README.rst
+++ b/README.rst
@@ -2,21 +2,29 @@ Sphinx Problem Matcher
 ======================
 
 This action adds a problem matcher that catches Sphinx warnings
-to show them neatly inside your pull request like this:
+to show them neatly inside your pull requests.
 
-.. image:: https://i.imgur.com/xkUMS1a.png
-   :alt: Example Screenshot
+Usage
+-----
 
-The common usage of this will be like so:
+We suggest using the action as shown below,
+simply running the action before building your documentation.
+
+**Note: This action does not handle actually building your docs.**
 
 .. code-block:: yaml
 
    - uses: sphinx-doc/github-problem-matcher@master
+
    - name: "Build docs"
      run: |
        cd docs
        make html
 
-That is, simply run this action before building your docs.
+Example
+-------
 
-**Note: this does not handle actually building your docs.**
+After using the action, files in pull requests will be annotated:
+
+.. image:: https://i.imgur.com/xkUMS1a.png
+   :alt: Example Screenshot