#3081 Docs readme gatsby transformer yaml (#3154)

* Adds modle.exports example

* Moves module.exports example to 'How to use'

* Describes Parsing algorithm

* Renames 'value' to 'character' to avoid confusion

* Renames more 'value' to 'character'; Changes 'allLetters' to 'allLettersYaml'

* Supported extensions, How to query, Note that you need files

* Notes that .yaml and .yml are used in the same way.

packages/gatsby-transformer-yaml/README.md

@@ -2,25 +2,46 @@
 
 Parses YAML files. Supports arrays of objects and single objects.
 
+Supported extensions: `.yaml`, `.yml`
+
+Both `.yaml` and `.yml` are treated in the same way. This document uses both of them interchangably.
+
 ## Install
 
 `npm install --save gatsby-transformer-yaml`
 
-You also need to have `gatsby-source-filesystem` installed and configured so it
+__Note:__ You also need to have `gatsby-source-filesystem` installed and configured so it
 points to your files.
 
 ## How to use
 
+In your `gatsby-config.js`
+
 ```javascript
-// In your gatsby-config.js
-plugins: [`gatsby-transformer-yaml`];
+module.exports = {
+  plugins: [
+    `gatsby-transformer-yaml`,
+    {
+      resolve: `gatsby-source-filesystem`,
+      options: {
+        path: `./src/data/`
+      }
+    }
+    ],
+}
 ```
 
+Where the _source folder_ `./src/data/` contains the `.yaml` files.
+
 ## Parsing algorithm
 
 You can choose to structure your data as arrays of objects in individual files
 or as single objects spread across multiple files.
 
+The _source folder_ can contain either the following:
+  - __Array of Objects__: Where each file represents a collection. (_you probably want this one_)
+  - __Single Object__: Where each _subfolder_ represents a collection; each files represents one "record".
+
 ### Array of Objects
 
 The algorithm for YAML arrays is to convert each item in the array into a node.
@@ -29,26 +50,23 @@ The type of the node is based on the filename.
 So if your project has a `letters.yaml` which looks like:
 
 ```yaml
-- value: a
-- value: b
-- value: c
+- character: a
+- character: b
+- character: c
 ```
 
 Then the following three nodes would be created.
 
 ```javascript
 [
   {
-    value: "a",
-    type: "Letters",
+    character: "a"
   },
   {
-    value: "b",
-    type: "Letters",
+    character: "b",
   },
   {
-    value: "c",
-    type: "Letters",
+    character: "c",
   },
 ];
 ```
@@ -72,44 +90,43 @@ data/
 Where each of `a.yml`, `b.yml` and `c.yml` look like:
 
 ```yaml
-value: a
+character: a
 ```
 
 ```yaml
-value: b
+character: b
 ```
 
 ```yaml
-value: c
+character: c
 ```
 
 Then the following three nodes would be created.
 
 ```javascript
 [
   {
-    value: "a",
-    type: "Letters",
+    character: "a",
   },
   {
-    value: "b",
-    type: "Letters",
+    character: "b",
   },
   {
-    value: "c",
-    type: "Letters",
+    character: "c",
   },
 ];
 ```
 
 ## How to query
 
+You can query the nodes using `GraphQL`, like from the GraphiQL browser: `localhost:8000/___graphql`.
+
 Regardless of whether you choose to structure your data in arrays of objects or
 single objects, you'd be able to query your letters like:
 
 ```graphql
 {
-  allLetters {
+  allLettersYaml {
     edges {
       node {
         value
@@ -123,24 +140,26 @@ Which would return:
 
 ```javascript
 {
-  allLetters: {
+  allLettersYaml: {
     edges: [
       {
         node: {
-          value: "a",
+          character: "a",
         },
       },
       {
         node: {
-          value: "b",
+          character: "b",
         },
       },
       {
         node: {
-          value: "c",
+          character: "c",
         },
       },
     ];
   }
 }
 ```
+
+Please do __note__ that `allLettersYaml` __will not__ show up if you do not have any `.yaml` files.