Doc: Final polish

Siphonophora · Sep 13, 2020 · 2fe8bbd · 2fe8bbd
1 parent c89fd25
commit 2fe8bbd
Show file tree

Hide file tree

Showing 6 changed files with 20 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 - [Sql Data Compare](#sql-data-compare)
-- [Using the App](#using-the-app)
-- [Privacy and Security](#privacy-and-security)
-- [Support](#support)
-- [Requirements](#requirements)
+  - [Using the App](#using-the-app)
+  - [Privacy and Security](#privacy-and-security)
+  - [Support](#support)
+  - [Requirements](#requirements)
 
 # Sql Data Compare
 
@@ -14,20 +14,20 @@ The script will produce a report like the one below, if all the rows are identic
 
  ![results](docs/book_comparison_passing.PNG)
 
-# Using the App
+## Using the App
 
 Instructions for using the app can be found in the 
 [Usage Guide](docs/usage_guide.md).
 
-# Privacy and Security
+## Privacy and Security
 
 The [Privacy and Security](docs/privacy_security.md) page discusses safety of the app and the generated templates.
 
-# Support
+## Support
 
 If you are having any issue with the app, have questions, or would like to request a feature, then please open an issue.
 
-# Requirements
+## Requirements
 
 The [web app][webapp] should run on any modern browser, except Internet Explorer. 
 

diff --git a/docs/book_comparison_passing.PNG b/docs/book_comparison_passing.PNG
diff --git a/docs/book_query_in_app.PNG b/docs/book_query_in_app.PNG
diff --git a/docs/book_query_in_app_copy.PNG b/docs/book_query_in_app_copy.PNG
diff --git a/docs/privacy_security.md b/docs/privacy_security.md
@@ -9,16 +9,16 @@ Below are a few notes on privacey and security related to using this app.
 
 ## Your SQL never leaves your browser.
 
-If you are using the web app [hosted here][webapp] you may wonder if the sql you are pasting into the app is sent to a remote server somewhere to be parsed. All of the code for this utility runs locally in your browser. As a result **your SQL never leaves your machine**. The specific technology is [Blazor Web Assembly](https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor). 
+If you are using the web app [hosted here][webapp] you may wonder if the sql you are pasting into the app is sent to a remote server somewhere to be processed. The answer is no. All of the code for this utility runs locally in your browser. As a result **your SQL never leaves your machine**. The specific technology is [Blazor Web Assembly](https://dotnet.microsoft.com/apps/aspnet/web-apps/blazor). 
 
 You are, of course, welcome to run the application locally on your own machine.
 
 ## Are the comparison templates safe?
 
-As a rule, taking code off the internet and running it on your own systems is not a great idea. This utility does two things to help ensure that the templates it produces are safe. 
+As a rule, taking code off the internet and running it on your own systems is not a great idea. This utility does two things to help ensure that the templates it produces are safe and trustworthy. 
 
-1. The first, and simplest to verify, is that the whole template is wrapped in a transaction that is rolled back. You can see the template begins with `BEGIN TRAN` and ends with `ROLLBACK TRAN`. Because there is no `COMMIT TRAN` anywhere in the output template, you can be confident that no perminent changes could happen in the template.
-2. The utility attempts to detect any sql which has side effects. For example, it checks for attemps to insert, update or delete to real tables or DML statements that would change the database itself. When these statements are encountered, the utility will not produce a template. On the other hand, it is allowable to create and work with temp tables in the template.
+1. The first, and simplest to verify, is that the whole template is wrapped in a transaction that is rolled back. You can see the script begins with `BEGIN TRAN` and ends with `ROLLBACK TRAN`. Because there is no `COMMIT TRAN` anywhere in the output script, you can be confident that no perminent changes could happen as a result of running the script.
+2. The utility attempts to detect any sql which has side effects. For example, it checks for attemps to insert, update or delete to real tables or DML statements that would change the database itself. When these statements are encountered, the utility will output a warning and will not produce a script. On the other hand, it is allowable to create and work with temp tables in the template.
 
 ## Analytics
 

diff --git a/docs/usage_guide.md b/docs/usage_guide.md
@@ -68,7 +68,10 @@ From SciFiBooks
  ![results](book_query_in_app.PNG)
 
 5. Copy the comparison script.
-6. Run the query, which produces the output below.
+
+ ![results](book_query_in_app_copy.PNG)
+
+6. Run the query in the test database. The output below will be produced.
 
 As we can see, the query has correctly found the following:
 * 3 rows are identical.
@@ -85,7 +88,7 @@ Here are a few more advanced considerations.
 
 ### Key Selection
 
-When choosing keys, you must pick at least one key and the key(s) you choose must be uniquely represent a row of the results. Once you met this requirement you can still select *more* columns as keys. 'Over defining' the keys can substantially alter the results of the comparison. If we take the book query above, and compare using Id, or Auhtor and ID we get different results. As [discussed below](#comparing-many-parameterized-query-results), adding the extra key is equivelent to comparing the results of querying for each author one at a time. 
+When choosing keys, you must pick at least one key and the key(s) you choose must be uniquely represent a row of the results. Once you met this requirement you can still select *more* columns as keys. 'Over defining' the keys can substantially alter the results of the comparison. This is particularly true when working on queries with complex joins. If we take the book query above, and compare using Id, or Auhtor and ID we get different results. As [discussed below](#comparing-many-parameterized-query-results), adding the extra key is equivelent to comparing the results of querying for each author one at a time. 
 
 In the results, we can see that we now have more missing and extra columns. Discrepancies only show up where the author matches, as well as the key.
 
@@ -126,7 +129,7 @@ Several temp table names are reserved for use by the app.
 
 ### Parameterized Queries
 
-If paramaterized queries share the same parameter names, you can paste the parameter declarations into the template after it is created. There is a section at the top of the template for this purpose. Which makes it easy to find and change the parameter as needed.
+If paramaterized queries share the same parameter names, you can paste the parameter declarations into the template after it is created. There is a section at the top of the template for this purpose. This makes it easier to find and change the parameter as needed, than if you include it in the `Assert` or `Test` sql.
 
 ### Comparing Many Parameterized Query Results
 
@@ -147,7 +150,7 @@ From SciFiBooks
 Where Author = @Author
 ```
 
-We can modify the queries to allow us to the output of this query, for every value of `@Author` that returns results. We do this by removing the parameter(s) and instead adding them to the select. We then add the parameters to the beginning of the list of keys, so we now have `Author, Id` as keys. If your tables **a very large** you may want to be cautious about taking this approach. Another alternative would be to create a temp table with a subset of authors to test, and add `where Author in (Select Author from #TestAuthors)` to the query.
+We can modify the queries to allow us to simulate the output of this query for every value of `@Author` that returns results. We do this by removing the parameter(s) and instead adding them to the select ed colums. We then also add the parameters to the beginning of the list of keys, so we now have `Author, Id` as keys. If your tables **are very large** you may want to be cautious about taking this approach from a performance perspective. A more performant option might be to create a temp table with a subset of authors to test, and add `where Author in (Select Author from #TestAuthors)` to the query.
 
 ``` sql
 -- Assert
@@ -164,6 +167,6 @@ This yields quite a different result from the Getting Started example above, whe
 
 ### Stored Procedures
 
-This tool does not directly support stored procedures. However, you can take the code from the stored procedures and running it as a paramaterized query.
+This tool does not directly support stored procedures. However, you can take the code from the stored procedures and run it as a [paramaterized query](#parameterized-queries).
 
 [webapp]: https://siphonophora.github.io/SqlDataCompare/