Merge pull request #367 from mdyd-dev/getstarted-updates2

Updates Get Started tutorials pt2

marketplace_builder/views/pages/get-started/creating-codebase.liquid

@@ -9,7 +9,7 @@ searchable: true
 
 This guide will help you create the codebase using the Marketplace Kit.
 
-In order to correctly communicate with the platformOS engine and API, your codebase should be organized into a specific directory structure. The root directory of your project should contain the `marketplace_builder` directory. All directories other than the `marketplace_builder` will be ignored by the Marketplace Kit when deploying and syncing, so you can keep all your JS and CSS files outside of the `marketplace_builder` directory, and use any pre-processors you want to automatically generate the end result files in a proper path inside `marketplace_builder`.
+In order to correctly communicate with the platformOS engine and API, your codebase should be organized into a specific directory structure. The root directory of your project should contain the `marketplace_builder` directory. 
 
 {% capture content %}
 This guide explains how to create your codebase using the Marketplace Kit. Alternatively, you can create your directory structure by <a href="/tutorials/partner-portal/downloading-codebase-instance">Downloading the Codebase of an Instance</a> you created or have access to.
@@ -44,11 +44,11 @@ Marketplace Kit downloads the directory structure in a zip file, and extracts it
 
 Once you've downloaded the codebase, locate and explore it &ndash; this is how the directories and code of your platformOS Instances should be organized.
 
-To learn more about the required directories and files, see [platformOS Components](/how-platformos-works/platformos-workflow).
+To learn more about the required directories and files, check out our detailed description of the [platformOS Codebase](/how-platformos-works/platformos-workflow/codebase).
 
 ## Next steps
 
-Congratulations! You have created the required file structure for your codebase using the Marketplace Kit. You can now deploy and sync changes to your Instance.
+Congratulations! You have created the codebase for your Instance using the Marketplace Kit. You can now deploy and sync changes to your Instance.
 
 * [Deploying and Syncing Changes](/get-started/deploying-syncing-changes)
 

marketplace_builder/views/pages/get-started/deploying-syncing-changes.liquid

@@ -7,39 +7,86 @@ slug: get-started/deploying-syncing-changes
 searchable: true
 ---
 
-This guide will help you deploy and sync changes you make in your codebase to your Instance.
+This guide will help you deploy and sync changes you make in your codebase to your Instance. To demonstrate the process, you'll make a small change on your home page, and deploy it to your Instance. 
 
 ## Requirements
 
-In order to deploy and sync changes to your Instance, you will need an Instance set up on the Partner Portal, and the Marketplace Kit installed on your computer. You will also need to have the codebase for your Instance organized into the required directory structure – a way to set it up is by using the Blank Marketplace Module.
+In order to deploy and sync changes to your Instance, you will need an Instance set up on the Partner Portal, and the Marketplace Kit installed on your computer. You will also need to have the codebase for your Instance organized into the required directory structure.
 
 * [Setting Up a Site on Our Platform](/get-started/setting-up-site)
 * [Installing the Marketplace Kit](/get-started/installing-marketplace-kit)
 * [Creating the Codebase](/get-started/creating-codebase)
 
 ## Steps
 
-Deploying and syncing changes is a two-step process:
+Deploying and syncing changes is a three-step process:
 
-1.  Authenticate environments
-2.  Deploy or sync changes
+1.  Change something in your codebase
+2.  Authenticate environments
+3.  Deploy or sync changes
 
-### Step 1: Authenticate environments
+### Step 1: Change something in your codebase
 
-{% include 'alert/note', content: 'Run all commands discussed in this tutorial in the project root directory, i.e. one level above the `marketplace_builder` directory' %}
+Locate the `home.liquid` file in your codebase (`marketplace_builder/views/pages/home.liquid`). 
 
-Authentication is done with your **Partner Portal** account credentials.
-See this [guide](/get-started/accessing-partner-portal) if you don't have Partner Portal account yet.
+```liquid
+{% raw %}
+---
+slug: /
+layout_name: 1col
+---
+{%- assign name = 'Home' -%}
+{%- content_for 'pagetitle' -%}{{ name }}{%- endcontent_for -%}
+<h1>{{ name }}</h1>
+{% endraw %}
+```
+
+Open it in a code editor of your choice, and add some text. Don't edit the lines between `---`:
+
+```liquid
+{% raw %}
+---
+slug: /
+layout_name: 1col
+---
+{%- assign name = 'Home' -%}
+{%- content_for 'pagetitle' -%}{{ name }}{%- endcontent_for -%}
+<h1>{{ name }}</h1>
+Hello, World!
+{% endraw %} 
+```
+
+Save your changes.
+
+### Step 2: Authenticate environments
+
+{% include 'alert/note', content: 'Run all commands discussed in this tutorial in the project root directory, i.e. one level above the `marketplace_builder` directory.' %}
 
-To add your environment to a config file, run the `env add` command, and authenticate with your **Partner Portal** credentials:
+Authentication is done with your **Partner Portal** account credentials (email and password).
+
+To add your environment to the config file, run the `env add` command, and authenticate with your **Partner Portal** credentials:
+
+<pre class="command-line" data-user="user" data-host="host"><code class="language-bash">
+marketplace-kit env add [environment] --email [your email] --url [your Instance URL]
+</code></pre>
+
+Example: 
 
 <pre class="command-line" data-user="user" data-host="host"><code class="language-bash">
-marketplace-kit env add [environment] --email [your email] --url [your marketplace url]
+marketplace-kit env add staging --email myemail@example.com --url https://example.com
 </code></pre>
 
-### Step 2: Deploy or sync changes
+A message _"Environment [your Instance URL] as staging has been added successfully."_ is displayed. 
+
+### Step 3: Deploy or sync changes
 
-#### Deploying
+To be able to see your changes on your site, you have to deploy those changes to your Instance. 
+{% capture content %}
+This step describes three different methods. If this is your first go, we recommend to follow the process described in the "Deploying" section.
+{% endcapture %}
+{% include 'alert/note', content: content %}
+
+#### Deploying 
 
 To deploy all changes, run the `deploy` command:
 
@@ -53,7 +100,13 @@ Example:
 marketplace-kit deploy staging
 </code></pre>
 
-We recommend to first deploy to staging, test, and only then trigger a deployment to production. In practice, deploy creates a zip file that contains all your files, and sends it to the API. It is then processed in the background. We store each zip file, so that you can roll back in case something goes wrong.
+A progress indicator shows that the deployment is in progress, and once it finishes, a _"Deploy succeeded after <time>"_ is displayed.
+
+We recommend to first deploy to staging, test, and only then trigger a deployment to production. In practice, deploy creates a zip file that contains all your files, and sends it to the API. It is then processed in the background. We store each zip file, so that you can roll back in case something goes wrong. 
+{% capture content %}
+Learn more about our recommendations for version control and deployment on platformOS in the <a href="/how-platformos-works/platformos-workflow/development-workflow">Development Workflow</a> topic. 
+{% endcapture %}
+{% include 'alert/tip', content: content %}
 
 #### Syncing
 
@@ -69,7 +122,7 @@ Example:
 marketplace-kit sync staging
 </code></pre>
 
-Using the sync command feels like working on localhost. It is dangerous to use it on production (on a live site) &ndash; it is recommended to use it only for staging. Please note, that unlike deploy, this command will not delete resources when you delete the file.
+Using the sync command feels like working on localhost. It is recommended to use sync only for staging environments, as pushing changes immediately to production can be dangerous. Please note, that unlike deploy, this command will not delete resources when you delete the file.
 
 #### Deploying and overriding
 
@@ -85,9 +138,12 @@ Example:
 marketplace-kit deploy staging -f
 </code></pre>
 
+<br>
+After you have deployed your Instance, refresh your site in your browser. The home page has changed to include the text you added.  
+
 ## Next steps
 
-Congratulations! You can deploy and sync your codebase to your Instance. Now you can delve into learning more about development on platformOS.
+Congratulations! You can deploy and sync your codebase to your Instance. Now, you can delve into learning more about development on platformOS.
 
 * [Pages](/tutorials/pages/pages)
 

marketplace_builder/views/pages/get-started/installing-marketplace-kit.liquid

@@ -8,6 +8,10 @@ searchable: true
 ---
 
 This guide will help you install the platformOS Marketplace Kit, that allows you to easily deploy your configuration files and assets to our platform, and communicate with the platformOS API.
+{% capture content %}
+The <a href="/how-platformos-works/platformos-workflow/marketplace-kit">Marketplace Kit</a> provides a wide range of features beyond initializing your codebase, including syncing and deployment, auditing, data export and import, migrations, logging, and a GUI.
+{% endcapture %}
+{% include 'alert/tip', content: content %}
 
 ## Requirements
 
@@ -31,7 +35,7 @@ Start your command-line tool (e.g. Terminal on a Mac, or Git Bash on Windows), a
 npm install -g @platform-os/marketplace-kit
 </code></pre>
 
-If your node is installed for all users you might need to use `sudo` to install npm packages globally:
+If your Node.js is installed for all users you might need to use `sudo` to install NPM packages globally:
 
 <pre class="command-line" data-user="user" data-host="host"><code class="language-bash">
 sudo npm install -g @platform-os/marketplace-kit
@@ -65,8 +69,8 @@ If the Marketplace Kit has been installed correctly, running this command displa
 
 ## Next steps
 
-Congratulations! You have installed the Marketplace Kit. You can now deploy and sync changes to your Instance.
+Congratulations! You have installed the Marketplace Kit. You can now create your codebase. 
 
-* [Deploying and Syncing Changes](/get-started/deploying-syncing-changes)
+* [Creating the Codebase](/get-started/creating-codebase)
 
 {% include 'shared/questions_section' %}

marketplace_builder/views/pages/get-started/quickstart-guide.liquid

@@ -104,12 +104,13 @@ Once you've installed the required directory structure, locate and explore it &n
 
 In this final step, you'll make a small change on your home page, and deploy it.
 
-Locate the `home.liquid` file inside your marketplace directory (`marketplace_builder/views/pages/home.liquid`). Open it in a code editor of your choice, and change the text to anything you'd like to, but don't edit the first 3 lines:
+Locate the `home.liquid` file in your codebase (`marketplace_builder/views/pages/home.liquid`). Open it in a code editor of your choice, and change the text to anything you'd like to, but don't edit the first 3 lines:
 
 ```yaml
 ---
 slug: /
 ---
+Hello, World! 
 ```
 
 Save your changes.

marketplace_builder/views/pages/get-started/setting-up-site.liquid

@@ -43,7 +43,7 @@ We create the Instance, and once it's done, you receive an email with a link to
 
 Congratulations! You have created an Instance. Now make sure you have NPM installed on your system.  
 
-* [Installing NPM on a Mac](get-started/installing-npm-mac)
-* [Installing NPM on Windows](get-started/installing-npm-windows)
+* [Installing NPM on a Mac](/get-started/installing-npm-mac)
+* [Installing NPM on Windows](/get-started/installing-npm-windows)
 
 {% include 'shared/questions_section' %}