From 701f133dd92b135549305c3e6ee385d3bfeb9982 Mon Sep 17 00:00:00 2001
From: Luca Ban - Black Birdy <mesqueeb@gmail.com>
Date: Sun, 14 Oct 2018 19:10:24 +0900
Subject: [PATCH] =?UTF-8?q?update=20Docs=20=F0=9F=90=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/guide.md | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/docs/guide.md b/docs/guide.md
index 0f164c6a..470a6b36 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -6,8 +6,17 @@ Basically with just 4 actions (set, patch, insert, delete) you can make changes
 
 There are two ways to use vuex-easy-firestore, in 'collection' or 'doc' mode. You can only choose one because this points to the path you sync your vuex module to:
 
-- `firestoreRefType: 'collection'` for a firestore collection
-- `firestoreRefType: 'doc'` for a single firestore document
+**Collection mode**
+- `firestoreRefType: 'collection'`
+- `firestorePath` should be a firestore collection
+- Use when working with multiple documents, all docs will automatically be retrieved and sync when making changes.
+- eg. when a user has multiple "items" like a to-do list
+
+**Doc mode**
+- `firestoreRefType: 'doc'`
+- `firestorePath` should be a single firestore document
+- Use when working with a single doc.
+- eg. the "settings" or "config" of a user.
 
 Depending on which mode there are some small changes, but the syntax is mostly the same.
 
@@ -15,22 +24,26 @@ The sync is fully robust and **automatically groups any api calls per 1000 ms**.
 
 ## 'collection' mode
 
-With these 4 actions: set, patch, insert and delete, you can edit **single docs** in your vuex module. Any updates made with these actions will keep your firestore in sync!
+Opening [the DB channel](setup.html#open-db-channel) will retrieve all docs in your collection and add them to the vuex-module.
+
+Then with these 4 actions: set, patch, insert and delete, you can edit **single docs** of your collection. These actions make sure Firestore will stay in sync.
 
 ```js
-dispatch('moduleName/set', doc) // will choose to dispatch either `patch` OR `insert` automatically
+dispatch('moduleName/set', doc)
+// 'set' will choose to dispatch either `patch` OR `insert` automatically
+
 dispatch('moduleName/patch', doc) // doc needs an 'id' prop
 dispatch('moduleName/insert', doc)
 dispatch('moduleName/delete', id)
 ```
 
-There are two ways you can give a payload to `set`, `patch` or `insert`:
+**Inserting will automatically add an ID**, but for patching you will need to add the `id` to the payload. There are two ways you can do this:
 
 ```js
 const id = '123'
 // Add the `id` as a prop to the item you want to set/update:
 dispatch('moduleName/set', {id, name: 'my new name'})
-// Or use the `id` as [key] and the item as its value:
+// OR use the `id` as [key] and the item as its value:
 dispatch('moduleName/set', {[id]: {name: 'my new name'}})
 
 // Please note that only the `name` will be updated, and other fields are left alone!
@@ -56,6 +69,8 @@ dispatch('moduleName/delete', `${id}.tags.water`)
 
 In the above example you can see that you can delete a sub-property by passing a string and separate sub-props with `.`
 
+For batch actions see [here](#batch-updates-inserts-deletions).
+
 ### Auto-generated fields
 
 When working with collections, each document insert or update will automatically receive these fields:
@@ -87,11 +102,13 @@ dispatch('moduleName/insert', newDoc)
 
 As you can see in the example above, each vuex-easy-firestore module has a getter called `dbRef` with the reference of your `firestorePath`. So when you add `.doc().id` to that reference you will "create" a new ID, just how Firestore would do it. This way you can do whatever you want with the ID before / after the insert.
 
-Please note you can also access the ID (even if you don't manually pass it) in the [hooks](https://mesqueeb.github.io/vuex-easy-firestore/extra-features.html#hooks-before-insert-patch-delete).
+Please note you can also access the ID (even if you don't manually pass it) in the [hooks](extra-features.html#hooks-before-insert-patch-delete).
 
 ## 'doc' mode
 
-In 'doc' mode all changes will take effect on the single document you have passed in the firestorePath. You will be able to use these actions:
+In 'doc' mode all changes will take effect on the single document you have passed in the firestorePath.
+
+You will be able to use these actions:
 
 ```js
 dispatch('moduleName/set', {name: 'my new name'}) // same as `patch`