Merge pull request #249 from globeandmail/docs/SIT-3007

SIT-3007: Add usage reasons to readmes

README.md

@@ -70,7 +70,21 @@ Once your credentials are validated and saved, your site is officially superchar
 
 ## Usage
 
-There are two ways that Sophi Site Automation results can be included in a WordPress site, via a Site Automation block and a direct integration with WP_Query.  More details on each of these options are described below.
+There are two potential ways to integrate Sophi Site Automation results with your WordPress site. The default approach includes a Sophi Site Automation block that integrates with `WP_Query` by injecting Posts IDs via the `posts_pre_query` filter that gets fetched later to return the actual Posts. In the same fashion, you can integrate Sophi results with your `WP_Query` object by setting the `sophi_curated_page` and `sophi_curated_widget` query parameters.
+
+More details on each of these two options are described below.  If you are not certain on the best integration approach, considering the following:
+
+Reasons to use the Site Automation block:
+- No additional development effort needed for initial Sophi integration
+- Immediate integration with Sophi Site Automation API and page/widget settings
+- Basic block display settings allow for basic configurations (show/hide post excerpt, author name, post date, featured image)
+
+Reasons to use the Query integration:
+- Can implement more custom caching and content fallback options
+- Can implement support into non-block editor setups
+- Likely more flexible for headless setups
+- Block editor is not in-use within your WordPress environment
+- You need an integration with Category/Taxonomy Pages and cannot integrate using a sidebar widget
 
 ### Site Automation block
 

readme.txt

@@ -50,7 +50,21 @@ Once your credentials are validated and saved, your site is officially superchar
 
 == Usage ==
 
-There are two ways that Sophi Site Automation results can be included in a WordPress site, via a Site Automation block and a direct integration with WP_Query.  More details on each of these options are described below.
+There are two potential ways to integrate Sophi Site Automation results with your WordPress site. The default approach includes a Sophi Site Automation block that integrates with `WP_Query` by injecting Posts IDs via the `posts_pre_query` filter that gets fetched later to return the actual Posts. In the same fashion, you can integrate Sophi results with your `WP_Query` object by setting the `sophi_curated_page` and `sophi_curated_widget` query parameters.
+
+More details on each of these two options are described below.  If you are not certain on the best integration approach, considering the following:
+
+Reasons to use the Site Automation block:
+- No additional development effort needed for initial Sophi integration
+- Immediate integration with Sophi Site Automation API and page/widget settings
+- Basic block display settings allow for basic configurations (show/hide post excerpt, author name, post date, featured image)
+
+Reasons to use the Query integration:
+- Can implement more custom caching and content fallback options
+- Can implement support into non-block editor setups
+- Likely more flexible for headless setups
+- Block editor is not in-use within your WordPress environment
+- You need an integration with Category/Taxonomy Pages and cannot integrate using a sidebar widget
 
 = Site Automation block =