general wordsmithing; add section headings to PREINSTALL (#351)

* wordsmith; add Additional setup section

* reformat see it in action into steps

* fix formatting of code snippet in see it in action

* wordsmith; add sections

* wordsmith

* wordsmith parameter descriptions

* wordsmith; add additional setup section

* h3s to h4s; remove space before bullet list

reduce potential for merge conflicts

* revert back the parameter descriptions

* add detailed config info section; remove how you add images

Author: rachelsaunders

firestore-send-email/POSTINSTALL.md

@@ -1,7 +1,25 @@
 ### See it in action
 
-To test out this extension, add a document with a `to` field and a `message` field to the `${param:MAIL_COLLECTION}` collection in the [Firebase console][mail_collection] or using the [Firebase Admin SDK][admin_sdk]:
+You can test out this extension right away:
 
+1.  Go to your [Cloud Firestore dashboard](https://console.firebase.google.com/project/${param:PROJECT_ID}/database/firestore/data).
+
+1.  If it doesn't already exist, create the collection you specified during installation: `${param:MAIL_COLLECTION}`.
+
+1.  Add a document with a `to` field and a `message` field with the following content:
+
+    ```
+    to: ['someone@example.com'],
+    message: {
+      subject: 'Hello from Firebase!',
+      text: 'This is the plaintext section of the email body.',
+      html: 'This is the <code>HTML</code> section of the email body.',
+    }
+    ```
+
+1.  In a few seconds, you'll see a `delivery` field appear in the document. The field will update as the extension processes the email.
+
+**Note:** You can also use the [Firebase Admin SDK][admin_sdk] to add a document:
 ```
 admin.firestore().collection('${param:MAIL_COLLECTION}').add({
   to: ['someone@example.com'],
@@ -13,7 +31,7 @@ admin.firestore().collection('${param:MAIL_COLLECTION}').add({
 }).then(() => console.log('Queued email for delivery!'));
 ```
 
-### Use this extension
+### Using this extension
 
 After its installation, this extension monitors all document writes to the `${param:MAIL_COLLECTION}` collection. Email is delivered based on the contents of the document's fields. The top-level fields specify the email's sender and recipients. The `message` field contains the details of the email to deliver, including the email body.
 
@@ -49,7 +67,6 @@ Available properties for the `message` field are:
 If you specified a "Templates collection" parameter during configuration of the extension, you can create and manage [Handlebars][handlebars] templates for your emails. Each document for a template should have a memorable ID that you use as the *template name* in the document that's written to your `${param:MAIL_COLLECTION}` collection.
 
 The template document can include any of the following fields:
-
 * **subject:** A template string for the subject of the email.
 * **text:** A template string for the plaintext content of the email.
 * **html:** A template string for the HTML content of the email.

firestore-send-email/PREINSTALL.md

@@ -1,4 +1,4 @@
-Use this extension to render and send emails that contain the information from documents added to Cloud Firestore.
+Use this extension to render and send emails that contain the information from documents added to a specified Cloud Firestore collection.
 
 Adding a document triggers this extension to send an email built from the document's fields. The document's top-level fields specify the email sender and recipients, including `to`, `cc`, and `bcc` options (each supporting UIDs). The document's `message` field specifies the other email elements, like subject line and email body (either plaintext or HTML)
 
@@ -16,14 +16,17 @@ admin.firestore().collection('mail').add({
 
 Because each email is built from a Cloud Firestore document, you can reference information stored in _other_ Cloud Firestore documents and fields, like image URLs.
 
-You can also optionally configure this extension to render emails using [Handlebar](https://handlebarsjs.com/) templates. Each template is a document stored in a Cloud Firestore collection.
+You can also optionally configure this extension to render emails using [Handlebar](https://handlebarsjs.com/) templates. Each template must be a document stored in a Cloud Firestore collection that you specify when configuring this extension.
 
-When you configure this extension, you'll need to supply your **SMTP credentials for mail delivery** and specify the Cloud Firestore collection where you'll add documents. If you want to use templates, you'll also need to specify the collection containing your template documents.
+When you configure this extension, you'll need to supply your **SMTP credentials for mail delivery**.
 
-### Billing
+#### Additional setup
 
-This extension uses other Firebase or Google Cloud Platform services which may have associated charges:
+Before installing this extension, make sure that you've [set up a Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project.
+
+#### Billing
 
+This extension uses other Firebase or Google Cloud Platform services which may have associated charges:
 - Cloud Firestore
 - Cloud Functions
 

firestore-shorten-urls/POSTINSTALL.md

@@ -1,6 +1,6 @@
 ### See it in action
 
-To test out this extension, follow these steps:
+You can test out this extension right away:
 
 1.  Go to the [Cloud Firestore tab](https://console.firebase.google.com/project/${param:PROJECT_ID}/database/firestore/data).
 
@@ -14,7 +14,7 @@ To test out this extension, follow these steps:
 
 This extension listens to the Cloud Firestore collection `${param:COLLECTION_PATH}`, then shortens any URL added to the field `${param:URL_FIELD_NAME}` in any document within that collection.
 
-This extension shortens the URL then saves it in the `${param:SHORT_URL_FIELD_NAME}` field of the same document like so:
+This extension saves the shortened URL in the `${param:SHORT_URL_FIELD_NAME}` field of the same document like so:
 
 ```
 {

firestore-shorten-urls/PREINSTALL.md

@@ -1,15 +1,20 @@
-Use this extension to create shortened URLs from URLs written to your Cloud Firestore instance. These shortened URLs are useful as display URLs.
+Use this extension to create shortened URLs from URLs written to Cloud Firestore. These shortened URLs are useful as display URLs.
 
-This extension listens to your specified Cloud Firestore collection, then shortens any URL added to a specified field in any document within that collection. This extension shortens the URL then saves it in a new field in the same document.
+This extension listens to your specified Cloud Firestore collection, then shortens any URL added to a specified field in any document within that collection. This extension saves the shortened URL in a new field in the same document.
 
 If the original URL in a document is updated, then the shortened URL will be automatically updated, too.
 
 This extension uses Bitly to shorten URLs, so you'll need to supply your Bitly access token as part of this extension's installation. You can generate this access token using [Bitly](https://bitly.com/a/oauth_apps).
 
-### Billing
+#### Additional setup
 
-This extension uses other Firebase or Google Cloud Platform services which may have associated charges:
+Before installing this extension, make sure that you've [set up a Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project.
+
+You must also have a Bit.ly account and access token before installing this extension.
 
+#### Billing
+
+This extension uses other Firebase or Google Cloud Platform services which may have associated charges:
 - Cloud Firestore
 - Cloud Functions
 

firestore-shorten-urls/extension.yaml

@@ -90,7 +90,7 @@ params:
     default: urls
     example: urls
     validationRegex: "^[^/]+(/[^/]+/[^/]+)*$"
-    validationErrorMessage: Must be a valid Cloud Firestore Collection
+    validationErrorMessage: Must be a valid Cloud Firestore collection
     required: true
 
   - param: URL_FIELD_NAME

firestore-translate-text/PREINSTALL.md

@@ -1,15 +1,18 @@
 Use this extension to translate strings (for example, text messages) written to a Cloud Firestore collection.
 
-Whenever a string is written to a specified field in any document within your specified Cloud Firestore collection, this extension translates the string into your specified target language(s). The source language of the string is automatically detected. This extension adds the translated string to a separate specified field in the same document.
+This extension listens to your specified Cloud Firestore collection. If a string is added to a specified field in any document with that collection, this extension translates the string into your specified target language(s). The source language of the string is automatically detected. This extension adds the translation(s) of the string to a separate specified field in the same document.
 
 You specify the desired target languages using ISO-639-1 codes. You can find a list of valid languages and their corresponding codes in the [Cloud Translate API documentation](https://cloud.google.com/translate/docs/languages).
 
 If the original non-translated field of the document is updated, then the translations will be automatically updated, as well.
 
-### Billing
+#### Additional setup
 
-This extension uses other Firebase or Google Cloud Platform services which may have associated charges:
+Before installing this extension, make sure that you've [set up a Cloud Firestore database](https://firebase.google.com/docs/firestore/quickstart) in your Firebase project.
+
+#### Billing
 
+This extension uses other Firebase or Google Cloud Platform services which may have associated charges:
 - Cloud Translation API
 - Cloud Firestore
 - Cloud Functions

storage-resize-images/PREINSTALL.md

@@ -4,20 +4,21 @@ When you upload an image file to your specified Cloud Storage bucket, this exten
 
 You can even configure the extension to create resized images of different dimensions for each original image upload. For example, you might want images that are 200x200, 400x400, and 680x680 - this extension can create these three resized images then store them in your bucket.
 
-To configure this extension, you specify a maximum width and a maximum height (in pixels, px). This extension keeps the aspect ratio of uploaded images constant and shrinks the image until the resized image's dimensions are at or under your specified max width and height. For example, say that you specify a max width of 200px and a max height of 100px. You upload an image that is 480px wide by 640px high, which means a 0.75 aspect ratio. The final resized image will be 75px wide by 100px high to maintain the aspect ratio while also being at or under both of your maximum specified dimensions.
+Another optional feature of this extension is to specify a [`Cache-Control` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for your resized image files.
 
-You can upload images using the [Cloud Storage for Firebase SDK](https://firebase.google.com/docs/storage/) for your platform (iOS, Android, or Web). Alternatively, you can upload images directly in the Firebase console's Storage dashboard.
+#### Detailed configuration information
 
-Another optional feature of this extension is to specify a [`Cache-Control` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for your resized image files.
+To configure this extension, you specify a maximum width and a maximum height (in pixels, px). This extension keeps the aspect ratio of uploaded images constant and shrinks the image until the resized image's dimensions are at or under your specified max width and height.
 
-### Additional setup
+For example, say that you specify a max width of 200px and a max height of 100px. You upload an image that is 480px wide by 640px high, which means a 0.75 aspect ratio. The final resized image will be 75px wide by 100px high to maintain the aspect ratio while also being at or under both of your maximum specified dimensions.
+
+#### Additional setup
 
 Before installing this extension, make sure that you've [set up a Cloud Storage bucket](https://firebase.google.com/docs/storage) in your Firebase project.
 
-### Billing
+#### Billing
 
 This extension uses other Firebase or Google Cloud Platform services which may have associated charges:
-
 - Cloud Storage
 - Cloud Functions