Merge pull request #17 from IBM/improve-guides

Improve guides

Author: edmundreinhardt

README.md

@@ -1,7 +1,8 @@
-## Start docs locally
+# Merlin Docs
 
-* clone repo
-* install docsify `npm i docsify-cli -g`
-* run local with `docsify serve docs/`
-* by default, runs on http://localhost:3000
-* Read more about Docsify
+Hands-On Documentation for IBM i Merlin repository.
+
+## What is this for?
+
+* This hands-on documentation is not meant to replace the official [IBM Documentation for Merlin](https://www.ibm.com/docs/en/merlin/1.0?topic=overview).
+* These guides are for users getting started with Merlin step-by-step.

docs/workshop/01_admin.md

@@ -1,11 +1,18 @@
 
 ## One-Time (Administrator) Preparation
 
+These set-up steps have already been run for you.  They are documented here for your awareness and education and will be useful when you want to set up Merlin in your own environment.
+
 After your Infrastructure has been installed/configured, but before you can actually start using Merlin:
 
-1. IBM i Integration in Merlin
-2. Create Application definition - source and object libraries
-3. (If needed) migrate source from physical files -> IFS -> git repo
+1. Configure git for Source Configuration Management  
+2. (If needed) migrate source from physical files -> IFS -> git repo
+3. IBM i Integration in Merlin
+4. Create Application definition - source and object libraries
+
+### Configuring of Source Control Management
+Modern application development presupposes good source control that can enable best practices.
+Git is the most popular source code which can be used to drived your CI/CD pipeline suing web-hooks that can trigger builds when certain events happen in git. There are many different web interfaces to git that help automate the development process.  These include Github, Gitlab and Gitbucket.  If this is hosted outside of Merlin than the git hook needs some firewall configuration to access the builders running in Merlin.  The sandobx environment is configured with Gitbucket running on the IBM i.  This means that no new server is required and everything runs within the same secure network.  The source for the demo the repository already contains the sample application source and the git hook is configured.  Arcad products clone source from the git repository when doing builds on the IBM i and the user profile launching this needs to have the ssh key set up to access the git repository.  This also taken care of the sandbox environmetn.
 
 ### IBM i integration in Merlin
 
@@ -15,12 +22,12 @@ After your Infrastructure has been installed/configured, but before you can actu
 
 6 actions on IBM i performed sequentially from Merlin by the Administrator: 
 
-1. Enable ansible
-2. Validate PTF level
-3. Install certificates
-4. Enable IBM i Developer
-5. Enable remote debugger
-6. Enable Arcad (install Arcad solutions on the target IBM i)
+1. Enable ansible (_this is the automation framework used for the subsequent steps_)
+2. Validate PTF level (_ensures that the IBM i is a the prequisite software level_)
+3. Install certificates (_are required to have encrypted HTTPS communications_)
+4. Enable IBM i Developer (_configures IBM i backend for Merlin_)
+5. Enable remote debugger (_configures IBM i backend for the debugger_)
+6. Enable Arcad (_install Arcad solutions on the target IBM i_)
 
 <!-- div:right-panel -->
 
@@ -36,10 +43,8 @@ After your Infrastructure has been installed/configured, but before you can actu
 
 <!-- div:left-panel -->
 
-All these prep steps can be done from Merlin GUI or green screen.
-
-*Green screen steps coming soon.*
-
+The Arcad application has already been created for you.  
+When doing this for your own application this can easily be done from with the IDE as an action on the IBM i project or alternatively it can be done through Arcad green screen commands. 
 <!-- div:right-panel -->
 
 ![](01/from_merlin.png)