readme updates

README.md

@@ -1,14 +1,14 @@
-# Architecture Aspect
+# Architecture Diagram Aspect
 
-This CDK Aspect traverse the tree to generate a GitHub / markdown compatible mermaid chart.
+This CDK Aspect traverses the stack to generate a GitHub / markdown compatible mermaid chart of the AWS Resources created by the stack.
 
-During each stack synthesis it will write a markdown file based on the stack's id.  For example:
+It outputs this as a markdown folder based on the stack's id.  For example:
 
 `new Stack(new App(), 'asdf');`
 
 would create a markdown file called `asdf.md`.
 
-On each subsequent synthesis, the Aspect will read the stack's existing markdown file (if it exists) and infer architecture changes b/w before and after.
+On each subsequent synthesis, the Aspect will read the stack's existing markdown file (if it exists) and infer architecture changes b/w before and after.  It will then replace the markdown file with a visual diff of the architecture (see examples below).
 
 This uses no external dependencies!
 
@@ -18,7 +18,7 @@ This uses no external dependencies!
 - Normal arrow lines indicate an existing linkage
 - dashed/dotted arrow lines indicate a removed linkage
 
-## Example - Simple Stack
+## Example 1 - Simple Stack
 
 ```mermaid
 graph LR;
@@ -28,7 +28,7 @@ classDef added fill:#cfc,stroke:#cfc,stroke-width:2px,color:black;
 classDef removed fill:#fcc,stroke:#fcc,stroke-width:2px,color:black;
 ```
 
-## Example - Queue Added to Stack
+## Example 2 - Queue Added to Stack
 
 ```mermaid
 graph LR;
@@ -40,7 +40,7 @@ classDef added fill:#cfc,stroke:#cfc,stroke-width:2px,color:black;
 classDef removed fill:#fcc,stroke:#fcc,stroke-width:2px,color:black;
 ```
 
-## Example - Stack re-synthed AFTER the queue was added
+## Example 3 - Stack re-synthed AFTER the queue was added
 
 ```mermaid
 graph LR;
@@ -52,7 +52,7 @@ classDef added fill:#cfc,stroke:#cfc,stroke-width:2px,color:black;
 classDef removed fill:#fcc,stroke:#fcc,stroke-width:2px,color:black;
 ```
 
-## Example - Queue Removed
+## Example 4 - Queue Removed
 
 ```mermaid
 graph LR;
@@ -64,7 +64,7 @@ classDef added fill:#cfc,stroke:#cfc,stroke-width:2px,color:black;
 classDef removed fill:#fcc,stroke:#fcc,stroke-width:2px,color:black;
 ```
 
-## Example - Stack re-synthed AFTER the queue was removed
+## Example 5 - Stack re-synthed AFTER the queue was removed
 
 ```mermaid
 graph LR;