small readme clarification

README.md

@@ -44,8 +44,10 @@ const { GoogleSpreadsheet } = require('google-spreadsheet');
 // Initialize the sheet - doc ID is the long id in the sheets URL
 const doc = new GoogleSpreadsheet('<the sheet ID from the url>');
 
-// Initialize Auth - see more available options at https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication
+// Initialize Auth - see https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication
 await doc.useServiceAccountAuth({
+  // env var values are copied from service account credentials generated by google
+  // see "Authentication" section in docs for more info
   client_email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
   private_key: process.env.GOOGLE_PRIVATE_KEY,
 });

docs/README.md

@@ -48,8 +48,10 @@ const { GoogleSpreadsheet } = require('google-spreadsheet');
 // Initialize the sheet - doc ID is the long id in the sheets URL
 const doc = new GoogleSpreadsheet('<the sheet ID from the url>');
 
-// Initialize Auth - see more available options at https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication
+// Initialize Auth - see https://theoephraim.github.io/node-google-spreadsheet/#/getting-started/authentication
 await doc.useServiceAccountAuth({
+  // env var values are copied from service account credentials generated by google
+  // see "Authentication" section in docs for more info
   client_email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
   private_key: process.env.GOOGLE_PRIVATE_KEY,
 });

docs/classes/google-spreadsheet-worksheet.md

@@ -61,7 +61,9 @@ Property|Type|Description
 
 ### Working With Rows
 
-The row-based interface is provided as a simplified way to deal with sheets that are being used like a database (first row is column headers). In some situations it is much easier, but it comes with many limitations, so beware.
+The row-based interface is provided as a simplified way to deal with sheets that are being used like a database (first row is column headers). In some situations it is much simpler to use, but it comes with many limitations, so beware.
+
+Also note that the row-based API and cell-based API are isolated from each other, meaning when you load a set of rows, the corresponding cells are not loaded as well. You usually want to use one or the other.
 
 #### `loadHeaderRow()` (async) :id=fn-loadHeaderRow
 > Loads the header row (first row) of the sheet
@@ -122,6 +124,8 @@ Param|Type|Required|Description
 
 ### Working With Cells
 
+The cell-based interface lets you load and update individual cells in a sheeet, including things like the formula and formatting within those cells. It is more feature rich, but tends to be more awkward to use for many simple use cases.
+
 #### `loadCells(filters)` (async) :id=fn-loadCells
 > Fetch cells from google
 
@@ -170,6 +174,8 @@ Param|Type|Required|Description
 #### `saveUpdatedCells()` (async) :id=fn-saveUpdatedCells
 > saves all cells in the sheet that have unsaved changes
 
+!> NOTE - this method will only save changes made using the cell-based methods described here, not the row-based ones described above
+
 - ✨ **Side effects** - cells are saved, data refreshed from google
 
 #### `saveCells(cells)` (async) :id=fn-saveCells
@@ -199,8 +205,8 @@ Param|Type|Required|Description
 
 Param|Type|Required|Description
 ---|---|---|---
-`range`|[[GridRange](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#GridRange)]|✅|Range of cells to merge, sheetId not required!
-`mergeType`|String (enum)<br>[MergeType](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#MergeType|-|defaults to MERGE_ALL
+`range`|Object<br>[GridRange](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#GridRange)|✅|Range of cells to merge, sheetId not required!
+`mergeType`|String (enum)<br>[MergeType](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#MergeType)|-|defaults to MERGE_ALL
 
 - 🚨 **Warning** - Reading values from merged cells other than the top-left one will show a null value
 
@@ -209,7 +215,7 @@ Param|Type|Required|Description
 
 Param|Type|Required|Description
 ---|---|---|---
-`range`|[[GridRange](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#GridRange)]|✅|Range of cells to unmerge, sheetId not required!
+`range`|Object<br>[GridRange](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#GridRange)]|✅|Range of cells to unmerge, sheetId not required!
 
 ### Updating Sheet Properties
 

docs/classes/google-spreadsheet.md

@@ -83,7 +83,7 @@ Property|Type|Description
 
 Param|Type|Required|Description
 ---|---|---|---
-`creds`|Object|✅|Object containing credendtials from google for your service account<br>_usually just `require` the json file google gives you_
+`creds`|Object|✅|Object containing credentials from google for your service account<br>_usually just `require` the json file google gives you_
 `creds.client_email`|String<br>_email_|✅|The email of your service account
 `creds.private_key`|String|✅|The private key for your service account
 `impersonateAs`|String<br>_email_|-|Email of user to impersonate instead of authing as service account (only possible if service account has domain-wide delegation enabled)
@@ -92,7 +92,6 @@ Param|Type|Required|Description
 - ✨ **Side effects** - all requests will now authenticate using these credentials
 
 > See [Getting Started > Authentication > Service Account](getting-started/authentication#service-account) for more details
-http://localhost:3000/#/getting-started/authentication?id=service-account
 
 #### `useApiKey(key)` :id=fn-useApiKey
 > Set API-key to use for auth - only allows read-only access to public docs

docs/getting-started/authentication.md

@@ -52,7 +52,7 @@ const creds = require('./config/myapp-1dd646d7c2af.json'); // the file saved abo
 const doc = new GoogleSpreadsheet('<YOUR-DOC-ID>');
 await doc.useServiceAccountAuth(creds);
 
-// or preferably, loading that info from env vars / config instead of the file
+// or preferably, load that info from env vars / config instead of the file
 await doc.useServiceAccountAuth({
   client_email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
   private_key: process.env.GOOGLE_PRIVATE_KEY,
@@ -64,19 +64,32 @@ await doc.useServiceAccountAuth(creds, 'user.to.impersonate@mycompany.com');
 
 ```
 
-**SPECIAL NOTE FOR HEROKU USERS**
-Getting the key saved/retrieved properly can be a little tricky. Here's one way to get it to work
+**SPECIAL NOTE FOR HEROKU USERS (OR SIMILAR PLATFORMS)**
+
+Sometimes setting/retreiving config vars that include line breaks can get tricky.
+
+Here's one way to get it to work (using heroku cli):
 1. Save the private key to a new text file
 2. Replace `\n` with actual line breaks
 3. Replace `\u003d` with `=`
 4. run `heroku config:add GOOGLE_PRIVATE_KEY="$(cat yourfile.txt)"` in your terminal
 
+And in some other scenarios something like this can be helpful:
+```
+await doc.useServiceAccountAuth({
+  client_email: process.env.GOOGLE_SERVICE_ACCOUNT_EMAIL,
+  private_key: process.env.GOOGLE_PRIVATE_KEY.replace(/\\n/g, "\n"),
+});
+```
+
 
 ## 🔑 API Key :id=api-key
 **read-only access of public docs**
 
 Google requires this so they can at least meter your usage of their API.
 
+!> Allowing only read-only access using an API key is a limitation of Google's API (see [issuetracker](https://issuetracker.google.com/issues/36755576#comment3))
+
 __Setup Instructions__
 1. Follow steps above to set up project and enable sheets API
 2. Create an API key for your project