doc updates

asyncapi/README.md

@@ -59,7 +59,7 @@ decodable stream list -o json | \
 		> dp.json
 ```
 
-* There should be a YAML document {YOUR_ACCOUNT}.yaml in the local directory. Run the next command to create the html document. This will create a `output` directory. When this command finishes, you can run `open output/index.html` to see it in your browser.
+* There should be a YAML document {YOUR_ACCOUNT}.yaml in the local directory. Run the next command to create the html document. This will create a `output` directory. When this command finishes, you can run `open output/index.html` to see it in your browser. The command uses this [html generator](https://github.com/asyncapi/html-template).
 ```bash
 make html
 ```

asyncapi/templates/dp.decodable.yaml.j2

@@ -18,7 +18,7 @@ info:
     email: [email protected]
   x-twitter: '@AsyncAPISpec'
 
-tags:
+tags:  # a way to reference more metadata like lineage, usage metrics, and security information
   - name: root-tag1
     externalDocs:
       description: External docs description 1
@@ -34,7 +34,7 @@ tags:
     externalDocs:
       url: "https://www.asyncapi.com/"
 
-servers:
+servers: # decodable is serverless. For now we will push this data to you
   decodable:
     url: https://decodable.co
     protocol: decodable
@@ -46,7 +46,7 @@ defaultContentType: application/json
 
 channels:
 {% for stream in dp %}
-  {{ stream.name }}:
+  {{ stream.name }}: # the stream name in decodable
     x-confluent-cloud-security:
       $ref: '#/components/securitySchemes/user-password'
     description: Subscribe to {{ stream.name }}. Created {{ stream.create_time }}. Updated {{ stream.update_time }}. Id {{ stream.id }}
@@ -114,7 +114,7 @@ components:
     {% for stream in dp %}
     {{ stream.name }}:
       bindings:
-        decodable:
+        decodable: # decodable specific bindings
           groupId: {{ stream.name }}
           clientId: {{ stream.name }}
           streamId: {{ stream.id }}