MAGETWO-91200: Update documentation for PageBuilder EAP

- update documentation

Author: Igor Melnikov

app/code/Magento/PageBuilder/docs/architecture-overview.md

@@ -21,7 +21,7 @@ For storage (later master format) Page Builder uses XHTML with inline styles and
 To display Page Builder content on storefront Magento and third party systems need to do the following
 
 1. Replace Magento directives (for instance {{image url=path/to/image.png}}).
-2. Add custom stylesheet.
+2. Add custom stylesheet to provide base styles that user can't edit (this includes styles for the content types like `slider`, `tabs`, `accordion`, etc).
 3. After content is rendered, on the frontend find all of content types that need to have widgets initialized (for instance, slider, tabs, etc) and load and initialize these widgets.
 
 See more on [master format](master-format.md)
@@ -54,14 +54,18 @@ Page Builder also would be enabled in custom extensions where WYSIWYG is used.
 
 Here is simplified data flow:
 1. Data read by reader `Magento_PageBuilder/js/master-format/read/configurable`.
-2. Data for each element (`border`, `border_color`, `border_width` etc) converted to internal format.
+2. Data for each element (`border`, `border_color`, `border_width` etc) converted to internal format by element converters.
 3. Data converted by mass converters, for more details see [converter interface](content-type-configuration.md).
 4. Content type created and `Magento_PageBuilder/js/data-store` populated with data.
-5. Data in data store modified and updated in data store.
+5. Data in data store modified in the form or using live edit.
 6. Data converted by mass converters.
-7. Converted by element converters.
+7. Converted by element data converters.
 8. Preview and master component observables updated.
-9. Attribute that editable with Page Builder updated, master format hen user saves pages data saved to the database.
+9. Editable with Page Builder entity attribute updated, when user saves the pages master format being saved to the database.
+
+Mass converter modifies on data for all content type elements. For instance, if content type two elements, main and image. And data for these elements stored in the fields `border`, `border_color`, `border_width`, `background_image`. Mass converter will allow to modify all these fields. See more on how [data stored internally](#Data store).
+
+Element converter modifies single field at a time.
 
 ## Data store
 

app/code/Magento/PageBuilder/docs/content-type-configuration.md

@@ -1,7 +1,7 @@
 # Content Type Configuration
 
 **Note:**
-*We are revising configuration, format may change.*
+*We are revising configuration, format will change. We will publish draft of new improved configuration soon to get feedback.*
 
 ## Navigation
 
@@ -239,7 +239,8 @@ It reads data based on the configuration specified in `data_mapping`.
 </appearance>
 ```
 
-Every content type needs a default appearance.
+Every content type requires a default appearance to ensure that other modules are able to easily add more appearances.
+
 Set the `default` attribute to "true" in an `appearance` node to set the default appearance for a content type.
 
 ### `data_mapping` configuration reference
@@ -248,11 +249,11 @@ Set the `default` attribute to "true" in an `appearance` node to set the default
 | ------------------ | ----------------------------------------------------------------------------------------------------- |
 | `elements`         | The container for all the elements of the content type.                                               |
 | `element`          | The name of the element that contains data for the master format and the render and preview template. |
-| `style_properties` | specifies styles properties for the element in the master format                                      |
-| `attributes`       | specifies attributes for the element in master format                                                 |
-| `css`              | specifies whether element has classes and in which variable they should be read                       |
-| `html`             | specifies whether element has html content and in which variable they should be read                  |
-| `tag`              | Allows you to read the tag value of the element and map it back to the master format.                 |
+| `style_properties` | Specifies styles properties for the element in the master format                                      |
+| `attributes`       | Specifies attributes for the element in master format                                                 |
+| `css`              | Specifies whether element has classes and in which variable they should be read                       |
+| `html`             | Specifies whether element has html content and in which variable they should be read                  |
+| `tag`              | Allows you to read the tag name of the element and map it back to the master format.                 |
 
 **Example:**
 ``` xml
@@ -361,7 +362,7 @@ These style properties and attributes are applied in the preview and persisted i
 
 ### Html element
 
-The `html` element allows you to read the value of the element in a property and map it back to the master format.
+The `html` element allows you to read the innerHTML of the element in a property and map it back to the master format.
 
 ``` xml
 <html name="message"/>
@@ -384,7 +385,7 @@ These classes are not read and do not appear on the form.
 
 ### Tag element
 
-The `tag` element allows you to read the tag value of the element and map back to the master format.
+The `tag` element allows you to read the tag name of the element and map back to the master format.
 
 ``` xml
 <tag name="heading_type"/>

app/code/Magento/PageBuilder/docs/how-to-add-new-content-type.md

@@ -87,6 +87,7 @@ Preview template `app/code/Vendor/ModuleName/view/adminhtml/web/template/content
 ``` HTML
 <div class="pagebuilder-content-type pagebuilder-entity pagebuilder-entity-preview" event="{mouseover: onMouseOver, mouseout: onMouseOut}, mouseoverBubble: false">
     <div attr="data.main.attributes" ko-style="data.main.style" css="data.main.css" html="data.main.html"></div>
+    <!-- Display context menu options for content type -->
     <render args="getOptions().template" />
 </div>
 ```
@@ -174,6 +175,8 @@ In the `simple.xml` above we defined border attributes and form for component. L
 </form>
 ```
 
+Every form should have default appearance to allow other modules to add more appearances.
+
 Attributes that we want to edit as part of the advanced section are defined in `pagebuilder_base_form`, so we can just extend it.
 
 And to allow this form to be loaded in PageBuilder, let's create layout `Vendor/ModuleName/view/adminhtml/layout/pagebuildercustom_simple_form.xml`.

app/code/Magento/PageBuilder/docs/install.md

@@ -31,19 +31,18 @@ Use this method if you are testing and evaluating PageBuilder for your Magento s
 
 ### Prerequisites
 
-* Magento 2.3
-* Access to PageBuilder in Magento's composer repository
-* Composer
+* You submitted us MAGEID and github username and received access to 2.3 alpha and PageBuilder. If you didn't submit us github username with will send you an email and request it.
 
 ### Installation steps
 
 1. Navigate to the root directory of your Magento application
-1. Add the PageBuilder package to the `composer.json` file using the following command:
-    <!-- Need to confirm this is correct -->
+2. Install 2.3 alpha, run composer create-project --repository-url=https://repo.magento.com/ magento/project-enterprise-edition=2.3.0-alpha20
+    Enter keys that you crated in your account (go to Marketplace / My Profile / Access Keys)
+3. Install Page Builder
     ``` sh
-    composer require magento/module-page-builder
+    composer require magento/module-page-builder-commerce
     ```
-1. Download and install PageBuilder into Magento using the following command:
+4. Enable Page Builder module using the following command:
     ``` sh
     bin/magento setup:upgrade
     ```
@@ -64,24 +63,33 @@ Do not use this installation method for evaluation or production instances.
 ### Installation steps
 
 1. Navigate to the root directory of your Magento application
-1. Clone the PageBuilder repository as a sub-directory using the following command:
+2. Clone the PageBuilder repository as a sub-directory using the following command:
     ``` sh
     git clone [email protected]:magento/magento2-page-builder.git pagebuilder
     ```
-1. Navigate to the `pagebuilder` directory and install PageBuilder dependencies using the following command:
-    ``` sh
-    cd pagebuilder && yarn
-    ```
-1. Return to the root directory of your Magento application and navigate to `app/code/Magento`
-1. In the Magento modules directory, link the PageBuilder module code to the application code using the following command:
+3. Return to the root directory of your Magento application and navigate to `app/code/Magento`
+4. In the Magento modules directory, link the PageBuilder module code to the application code using the following command:
     ``` sh
     ln -s ../../../pagebuilder/app/code/Magento/PageBuilder
     ```
-1. Return to the root directory of your Magento application and install the PageBuilder module using the following command:
+5. Return to the root directory of your Magento application and install the PageBuilder module using the following command:
     ``` sh
     bin/magento setup:upgrade
     ```
 
+## Installing Node.js dependencies
+
+If you plan to contribute to Page Builder, you need to install Node.js dependencies to compile TypeScript.
+
+Navigate to the `pagebuilder` directory and install PageBuilder dependencies using the following command:
+``` sh
+cd pagebuilder && yarn install
+```
+
+Then you can run `npx gulp` to watch changes to TypeScript files and compile.
+
+To check for TypeScript errors, you can run `npx tslint --fix -p tsconfig.json`.
+
 ## Activation
 
 Follow these steps to activate PageBuilder in the Admin:

app/code/Magento/PageBuilder/docs/master-format.md

@@ -351,7 +351,7 @@ HTML & JavaScript content.
 <figure data-role="image" data-appearance="full-width" data-lightbox="false" style="...">
     <a href="" title="">
         <img src="" title="" alt="" class="pagebuilder-mobile-hidden" />
-        <img src="" title="" alt="" class="pagebuilder-desktop-hidden" />
+        <img src="" title="" alt="" class="pagebuilder-mobile-only" />
     </a>
     <figcaption>Image description</figcaption>
 </figure>