MAGEDOC-3644: Post GA release docs cleanup

Re-reviewed and updated extension tutorial

Author: bdenham

docs/create-custom-content-type/step-6-add-icon.md

@@ -78,6 +78,6 @@ The last step is to add our icon's class name to our config file. Previous to th
 That's it. Now you can regenerate your static assets, empty your browser cache, and do a hard reload of your Admin page to see your new icon in the panel. 
 
 ## Next
-[Summary](summary.md).
+[Tutorial summary](summary.md).
 
 

docs/create-custom-content-type/summary.md

@@ -1,17 +1,26 @@
 # Summary
 
-If you made it this far, congratulations! We hope this tutorial has been useful to learning the basics of creating a completely new content type for your end-users.
+If you made it this far, congratulations! We hope this tutorial was useful for learning the basics of creating a completely new content type for your end-users. 
 
-Here's a list of good next topics to learn more about customizing Page Builder to meet your needs:
+## Next topics
+Here's a list of good next topics to learn more about customizing Page Builder:
+
+### Tutorials
 
 - [Extend an existing content type](../extend-existing-content-type/overview.md)
-- [How to customize the Page Builder panel](page-builder/docs/how-to/how-to-customize-panel.md)
-- [How to add an image uploader](page-builder/docs/how-to/how-to-add-image-uploader.md)
-- [How to add a storefront widget](page-builder/docs/how-to/how-to-add-storefront-widget.md)
-- [How to add a custom toolbar](page-builder/docs/how-to/how-to-add-custom-toolbar.md)
-- [How to add icons and images](page-builder/docs/how-to/how-to-add-icons-images.md)
-- [How to change breakpoints](page-builder/docs/how-to/how-to-change-breakpoints.md)
-- [Page Builder configurations](page-builder/docs/reference/configurations.md)
-- [Page Builder Datastore](page-builder/docs/reference/data-store.md)
-- [Page Builder events](page-builder/docs/reference/events.md)
-- [Page Builder Knockout bindings](page-builder/docs/reference/knockout-bindings.md)
+
+### How-Tos
+
+- [How to customize the Page Builder panel](../how-to/how-to-customize-panel.md)
+- [How to add an image uploader](../how-to/how-to-add-image-uploader.md)
+- [How to add a storefront widget](../how-to/how-to-add-storefront-widget.md)
+- [How to add a custom toolbar](../how-to/how-to-add-custom-toolbar.md)
+- [How to add icons and images](../how-to/how-to-add-icons-images.md)
+- [How to change breakpoints](../how-to/how-to-change-breakpoints.md)
+
+### Reference
+
+- [Page Builder configurations](../reference/configurations.md)
+- [Page Builder Datastore](../reference/data-store.md)
+- [Page Builder events](../reference/events.md)
+- [Page Builder Knockout bindings](../reference/knockout-bindings.md)

docs/extend-existing-content-type/overview.md

@@ -1,10 +1,10 @@
 # Overview
 
-One of quickest ways to customize Page Builder is by changing how _existing_ content types look and behave. End-users can already edit Page Builder's content types in several ways. But sometimes your end-users will want to change the structure or modify properties that do not exist on a given content type. In those cases, you can extend an existing content type by customizing its existing _appearance_ or adding a new _appearance_.
+One of the quickest ways to customize Page Builder is by changing how _existing_ content types look and behave. End-users can already use Page Builder's content types to customize their content using the form editor. But sometimes your end-users will want to change the structure or set properties that do not exist on the content type. In those cases, you can extend an existing content type by customizing its existing _appearance_ or adding a new _appearance_.
 
 ## Appearances
 
-An **appearance** is an XML element in a content type's configuration file that lets you modify existing properties, templates, styles, and form fields, or create new ones. In other words, all Page Builder content types (existing or custom) are extended through appearances.
+An **appearance** is an XML element (in the content type's config file) that defines a view for your content type. This view defines HTML templates, styles, form fields, and other elements, which you can customize in various ways. To extend existing Page Builder content types, you can either modify existing appearances or create new ones.
 
 Many of Page Builder's content types have only one `appearance` element. These include the Heading, Text, Image, Video, Tabs, and more. Other content types have several appearances. For example, the Banner content type has four appearances, as shown here:
 
@@ -21,7 +21,8 @@ Page Builder defines these appearances in the Banner's configuration file (`Mage
 </appearances>
 ```
 
-Within each `appearance` element, you can change content types in the following ways:
+In Page Builder 1.0.0, when you customize content types that have multiple appearances (like the Banner), you must apply your changes to all the appearances, not just one. Customizing a single appearance of a content type that defines multiple appearances is not currently supported.  
+You can use appearances to change content types in the following ways:
 
 - Add new style properties.
 - Add or change templates.
@@ -31,19 +32,19 @@ Within each `appearance` element, you can change content types in the following
 
 ## Banner extension tutorial
 
-In this tutorial, you will extend the Banner content type by adding a new `max-height` style property to two of the Banner's existing appearances: `collage-left` and `collage-right`.
+In this tutorial, you will learn how to extend one of Page Builder's existing content types by adding a new `max-height` style property to the Banner's existing appearances.
 
 ![Page Builder Banner menu item](../images/extend-banner-menu.png){:width="815px" height="auto"}
 
 ## Banner extension steps
 
-These steps show the basic pattern for adding style properties using existing appearances to extend a content type:
+These steps show the basic pattern for adding style properties and form fields to existing content type appearances:
 
 ![Creating Custom Content Types](../images/extension-steps-overview.svg)
 
 1. **Create an extension module**: Create a basic module for your Banner extensions.
 2. **Extend appearances**: Extend the existing content type's configuration file by customizing an existing appearance with new style properties.
-3. **Extend forms**: Extend the existing content type's UI component form by adding new form fields and changing defaults for existing fields.
+3. **Extend forms**: Extend the existing content type's UI component form by adding new form fields and/or changing defaults for existing fields.
 
 ## Next
 

docs/extend-existing-content-type/step-1-create-extension-module.md

@@ -1,16 +1,16 @@
 # Step 1: Create an extension module
 
-Appearance extensions for Page Builder are implemented using modules. In this step, we will create an empty module so we can add our appearance and form extensions in steps 2 and 3, as shown here:
+The first step to creating appearance customizations for existing Page Builder content types is to create a standard Magento module. In this step, we create an empty module so we can add our appearance and form extensions in steps 2 and 3:
 
 ![Completed extension file structure](../images/extension-file-structure-complete.png){:width="826px" height="auto"}
 
-## Add directory structure
+## Add a directory structure
 
 To create a module for the Banner extensions, name your vendor directory `Example` and name your module `PageBuilderExtensionBanner`, as shown here:
 
 ![Minimum extension module structure](../images/banner-extension-file-structure.png){:width="530px" height="auto"}
 
-The convention for naming extension modules is to prefix your extension of an existing content type with `PageBuilderExtension`, followed by the name of the content type. This is not a required convention, but we find that it helps visually group extension modules within your vendor directory.
+The convention for naming extension modules is to prefix your extension of an existing content type with `PageBuilderExtension`, followed by the name of the content type. This is not a required convention, but we find it helps group extension modules within your vendor directory.
 
 ## Add module file
 

docs/extend-existing-content-type/step-2-extend-appearances.md

@@ -1,10 +1,10 @@
 # Step 2: Extend appearances
 
-In this step, you will extend two of the four Banner appearances (`collage-left` and `collage-right`) by adding a new `max_height` style to each. This property stops the Banner from growing beyond a certain height as end-users enter text.
+In this step, you will extend all four Banner appearances by adding a new `max_height` style to each. The max-height property stops the Banner from growing beyond a certain height as end-users enter banner text.
 
 ## Create a content configuration file
 
-Appearances are defined in a content type's configuration file. As previously mentioned, the Banner's appearances are defined within the `banner.xml` file, as shown collapsed here:
+As mentioned before, Page Builder defines the Banner's appearances within the `banner.xml` configuration file, as shown collapsed here:
 
 ```xml
 <appearances>
@@ -15,13 +15,13 @@ Appearances are defined in a content type's configuration file. As previously me
 </appearances>
 ```
 
-Because we are extending the Banner, we start by creating a new configuration file called `banner.xml`.  Giving our extension configuration file the same name as the Banner's config file ensures that Magento will merge our appearance extensions with the Banner's existing configuration. Your file structure for the `banner.xml` extension should look like this:
+To customize these appearances, we need to create a new configuration file named `banner.xml`. Our configuration file must be the same name as the Banner's configuration file. This ensures that Magento merges our appearance customizations with the Banner's existing configuration. Your file structure for the `banner.xml` extension should look like this:
 
 ![Extension config file structure](../images/appearance-extension-config-file.png){:width="511px" height="auto"}
 
 ## Add properties to appearances
 
-Currently, you cannot extend just one appearance of a content type. You have to extend them all. In our example, we are extending the Banner content type, which has four appearances. Our example shows how you add a max-height property to all four of the Banner appearances.
+In the Page Builder 1.0.0 release, you cannot extend just one appearance of a content type. You must extend them all. In our example, we are extending all four appearances of the Banner content type by adding a max-height style property to these appearances:
 
 ```xml
 <?xml version="1.0"?>
@@ -67,10 +67,10 @@ The following table describes the elements in our extension configuration.
 | ------------- | ------------------------------------------------------------ |
 | `type`        | The type `name` defines the name of the content type. Make sure you name this configuration `banner` so that Magento will merge this configuration with the Banner's configuration. |
 | `appearances` | The grouping element that specifies one or more `appearance` elements. |
-| `appearance`  | The appearance `name` that Magento uses for XML merging. Again, make sure you  use the same appearance names as the Banner so that Magento can merge your appearance extensions with the Banner appearances you want to modify. |
+| `appearance`  | The appearance `name` that Magento uses for XML merging. Again, make sure you use the same appearance names as the Banner so that Magento can merge your appearance extensions with the Banner appearances you want to change. |
 | `elements`    | The grouping element that specifies one or more `element` nodes. |
-| `element`     | The element maps styles and other appearance extensions from the form editor to the HTML templates that render content on the Admin stage and storefront. We want our appearance styles to map to the `wrapper` element of the Banner's templates, so the element for each appearance extension is named `wrapper`. |
-| `style`       | The `style` element configures the bindings from the form field to the template elements. In this case, our style is applied to the `wrapper` element of the template. The style `name` represents the CSS `max-height` style. The `source` is the name of the form field you want the style bound to. Hint: The field name added in step 3 is `max-height`. |
+| `element`     | The `element` maps styles and other appearance extensions from the form editor to the HTML templates. In our markup, we map our new style properties for each appearance to the `wrapper` element of the Banner's HTML templates. |
+| `style`       | The `style` element configures the bindings from the form field to the HTML template elements. Here, we apply our style to the `wrapper` element of the template. The style `name` represents the CSS `max-height` style. The `source` is the name of the form field you want the style bound to. That means that the field name we will add in step 3 will be `max-height`. |
 {:style="table-layout:auto"}
 
 ## Next

docs/extend-existing-content-type/step-3-extend-forms.md

@@ -4,7 +4,7 @@ In this step, you will extend the Banner form (`pagebuilder_banner_form.xml`) by
 
 ## Create the appearance forms
 
-Page Builder forms are UI component forms. This means they follow the same conventions as any other UI component form. If you are not already familiar with UI component forms, you can learn more about them from the [UI Components Guide](https://devdocs.magento.com/guides/v2.3/ui_comp_guide/concepts/ui_comp_xmldeclaration_concept.html). For this tutorial, we provide you with the basic markup for setting up an empty form.
+Page Builder forms are UI component forms. This means they follow the same conventions as any other UI component form in Magento. If you are not already familiar with UI component forms, you can learn more about them from the [UI Components Guide](https://devdocs.magento.com/guides/v2.3/ui_comp_guide/concepts/ui_comp_xmldeclaration_concept.html). For this tutorial, we provide you with the basic markup for setting up an empty form.
 
 Your file structure for the Banner extension forms and corresponding layouts should look like this: 
 
@@ -53,7 +53,7 @@ When setting up your extension form, ensure you have named your form with the sa
 
 ## Add fieldsets and fields
 
-Before you add a field to the form of an existing content type, you need to know where to add it. In other words, you need to decide which fieldset to put your field in. We want to put our new max-height field with the Banner's existing min-height field, which is the `appearance_fieldset`.
+Before you add a field to the form of an existing content type, you need to know where to add it. In other words, you need to decide which fieldset to put your field in. We want to put our new max-height field below the Banner's existing min-height field, which is in the the `appearance_fieldset`.
 
 The markup for adding the field to the fieldset looks like this:  
 
@@ -83,20 +83,20 @@ The markup for adding the field to the fieldset looks like this:
 </fieldset>
 ```
 
-Some of the key elements are described here.
+The following table describes some key elements:
 
 | Elements   | Description                                                  |
 | ---------- | ------------------------------------------------------------ |
 | `fieldset` | The fieldset `name` should match the name of the fieldset from the Banner's form. The `appearance_fieldset` is common to all the content type forms and, by default, appears at the top of the forms using the `sortOrder` of 10. |
 | `field`    | The field `name` should match the CSS max-height style property, but in snake_case. Fields also have a `sortOrder` you can use to place your field above or below existing fields. The `formElement` for a field describes the HTML form type, such as input, checkbox, select, and more. |
-| `argument` | Provides the way to add a `default` value to your field. Our default value is set to `300`. |
+| `argument` | Provides the way to add a `default` value to your field. We set our default value to `300`. |
 | `settings` | Provides the markup that gives your field a label, CSS styling, validation, and other properties as needed. |
 {:style="table-layout:auto"}
 
-After adding max-height field as previously shown, flush your cache, drag a banner to the Admin stage, open the editor, and see your new style property field being rendered in the Banner's form, as shown here:
+After adding max-height field as shown, flush your cache, drag a banner to the Admin stage, open the editor, and see your new style property field being rendered in the Banner's form, as shown here:
 
 ![Appearance fieldset](../images/appearance-fieldset.png){:width="934px" height="auto"}
 
 ## Conclusion
 
-That's it! You should now be familiar with the basics of extending and existing content type. There is much more to learn, but hopefully this gives you a better understanding of how the existing Page Builder content types can be customized to fit your end-user's needs.
+That's it! You should now be familiar with the basics of extending an existing content type. There is much more to learn, but we hope this gives you a better understanding of how you can customize the existing Page Builder content types to fit your end-user's needs.