improve doc

doc/CONFIGURE_JENKINS.md

@@ -33,18 +33,18 @@ Quick reminder to install a plugin :
  5. Search for the plugin to install
  6. Check the box next to the plugin to install
  7. Click `Download now and install after restart`
- 8. Do not forget to check the box `Restart Jenkins`
+ 8. Do not forget to check the box `Restart Jenkins when installation is complete and no jobs are running`
 
-Note: to update a plugin, select the `Updates` tab instead of the `Available` tab.
+__Note :__ to update a plugin, select the `Updates` tab instead of the `Available` tab.
 
-## Create the Jenkins Pipeline
+## Create/Update the Jenkins Pipeline
 
 Depending if you created a JenkinsPipeline BuildConfig, OpenShift may have created
 a Jenkins pipeline for you. In such a case, the Jenkins Pipeline is named `<namespace>/<buildconfig-name>`.
 
 So, if you installed the demo :
  - manually, you need to create the pipeline from scratch
- - automatically, you need to update the pipeline to add the following parameters
+ - automatically with the provided template, you need to update the pipeline to add the following parameters
 
 __Note :__ As of today, OpenShift does not accept build environment variables with Jenkins pipelines.
 So you have to update the Jenkins pipeline created by OpenShift to add those variable.

doc/INSTALL.md

@@ -26,13 +26,19 @@ my other project : the [OpenShift-Hostpath-Provisioner](https://github.com/nmass
 
 Create all other objects using the template :
 ```
-oc process -f setup/all-in-one-template.yaml > objects.json
+oc process -f setup/all-in-one-template.yaml TEST_ROUTE_HOSTNAME=demo.test.app.openshift.test PROD_ROUTE_HOSTNAME=demo.prod.app.openshift.test NPM_EMAIL=your@npm.email > objects.json
 oc create -f objects.json
 ```
 
-Then, configure Jenkins [as described here](CONFIGURE_JENKINS.md).
+__Notes :__
+ - Keep the `objects.json` in a safe place since you will need it to cleanup the
+   platform (`oc delete -f objects.json`).
+ - Replace the `demo.test.app.openshift.test` and `demo.prod.app.openshift.test`
+   by meaningful values for your environment. It will be your routes in
+   TEST and PROD environments.
+ - Replace `your@npm.email` by the email address associated with your NPM Account.
 
-Where parameters are :
+All parameters are documented here :
 
 | Parameter Name | Required ? | Default Value | Description |
 | --- | --- | --- | --- |
@@ -49,6 +55,8 @@ Where parameters are :
 | TEST_PROJECT | No | demo-test | The name of the OpenShift Project to that holds the test environment |
 | PROD_PROJECT | No | demo-prod | The name of the OpenShift Project to that holds the prod environment |
 
+**Then, configure Jenkins [as described here](CONFIGURE_JENKINS.md).**
+
 ## Manual Setup
 
 Create the four environments :
@@ -154,4 +162,4 @@ oc set triggers dc/openshift-demo-nodejs-blue --from-image=demo-build/openshift-
 oc set triggers dc/openshift-demo-nodejs-green --from-image=demo-build/openshift-demo-nodejs:ready-for-prod --manual=true -c openshift-demo-nodejs-green -n demo-prod
 ```
 
-Then, configure Jenkins [as described here](CONFIGURE_JENKINS.md).
+**Then, configure Jenkins [as described here](CONFIGURE_JENKINS.md).**

doc/SCENARIO.md

@@ -1,5 +1,35 @@
 # Demo Scenario
 
+## Preparation
+
+If you plan to deliver this demo, you will need :
+ - a GitHub Account
+ - an NPM Account
+
+You will then need to clone this repo and edit `package.json` to change :
+ - the package name
+ - the package version
+
+__Note :__ You will have to change the package version each time you reset Jenkins
+since the build number is used in the NPM package version and the version numbers
+in NPM can only go up, never down.
+
+## Modify the app
+
+To run the following scenarios, you will have to modify the app to have a different color.
+Here is how to do so.
+
+Main steps :
+ - Edit `server.js` and modify line 7 (`var color = ...`) to have a different color.
+ - You can find nice colors [here](https://www.w3schools.com/cssref/css_colors.asp)
+ - Run the following commands :
+
+```
+git add server.js
+git commit -m 'improve look and feel'
+git push
+```
+
 ## Deploy in the DEV environment
 
 In this scenario, we are a developer joining an existing team. This developer
@@ -54,19 +84,3 @@ $ curl http://route.to.test.app/info
 $ curl http://route.to.test.app/info
 {"color":"purple","podName":"openshift-demo-nodejs-2-nsbv6"}
 ```
-
-## How to modify the app
-
-To run the previous scenarios, you will have to modify the app to have a different color.
-Here is how to do so.
-
-Main steps :
- - Edit `server.js` and modify line 7 (`var color = ...`) to have a different color.
- - You can find nice colors [here](https://www.w3schools.com/cssref/css_colors.asp)
- - Run the following commands :
-
-```
-git add server.js
-git commit -m 'improve look and feel'
-git push
-```