Merge pull request #112 from alanconway/tutorial-suggestions-1

Tutorial improvements 
 - fixing style
 - content clarity 
 - typos

Author: kameshsampath

02-basics/bin/call.sh

@@ -3,4 +3,4 @@
 INGRESSGATEWAY=istio-ingressgateway
 IP_ADDRESS="$(minishift ip):$(kubectl get svc $INGRESSGATEWAY --namespace istio-system --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')"
 
-curl -H "Host: greeter.knativetutorial.example.com" $IP_ADDRESS
+curl -H "Host:greeter.knativetutorial.example.com" $IP_ADDRESS

03-configs-and-routes/bin/call.sh

@@ -7,7 +7,7 @@ IP_ADDRESS="$(minishift ip):$(kubectl get svc $INGRESSGATEWAY --namespace istio-
 
 while true
 do
-  curl -H "Host: greeter.knativetutorial.example.com" $IP_ADDRESS 
+  curl -H "Host:greeter.knativetutorial.example.com" $IP_ADDRESS
   echo ""
   sleep .2
 done;

documentation/modules/ROOT/pages/02-basic-fundas.adoc

@@ -1,15 +1,16 @@
 = Basics and Fundamentals
 include::_attributes.adoc[]
 
-At the end of this chapter you will be able to understand and know how to :
+At the end of this chapter you will be able to :
 
-* Deploy first Knative service ?
-* Deploying multiple revisions of the service
-* What different service deployment strategies possible (service vs configurations/routes) ?
-* Always running latest vs pinning revision to services
+* Deploy a Knative service.
+* Deploy multiple revisions of a service.
+* Choose between different service deployment strategies.
+* Running different revisions of a service.
 
 [#basics-prerequisite]
-== Prerequisite 
+== Prerequisite
+
 include::partial$prereq-cli.adoc[]
 
 [#basics-build-containers]
@@ -102,7 +103,7 @@ include::partial$knative-objects.adoc[tag=knative-configs]
 === routes
 include::partial$knative-objects.adoc[tag=knative-routes]
 
-When the service was invoked with `curl -H "Host: greeter.knativetutorial.example.com" $IP_ADDRESS`,you noticed that we added a **Host** header to the request with value `greeter.knativetutorial.example.com`,this FQDN is automatically assigned to your Knative service by the Knative Routes,it uses the format like `**<service-name>.<namespace>.<domain-suffix>**`.
+When the service was invoked with `curl -H "Host:greeter.knativetutorial.example.com" $IP_ADDRESS`,you noticed that we added a **Host** header to the request with value `greeter.knativetutorial.example.com`,this FQDN is automatically assigned to your Knative service by the Knative Routes,it uses the format like `**<service-name>.<namespace>.<domain-suffix>**`.
 
 [NOTE]
 ====

documentation/modules/ROOT/pages/03-configs-and-routes.adoc

@@ -134,7 +134,7 @@ include::partial$knative-objects.adoc[tag=knative-configs]
 === routes
 include::partial$knative-objects.adoc[tag=knative-routes]
 
-When the service is invoked with `curl -H "Host: greeter.knativetutorial.example.com" $IP_ADDRESS`, you noticed that we added a **Host** header to the `curl` command with the value `greeter.knativetutorial.example.com`. This FQDN is automatically assigned to your Knative service by the Knative route we created. It follows a format `<route-name>.<namespace>.<domain-suffix>`.
+When the service is invoked with `curl -H "Host:greeter.knativetutorial.example.com" $IP_ADDRESS`, you noticed that we added a **Host** header to the `curl` command with the value `greeter.knativetutorial.example.com`. This FQDN is automatically assigned to your Knative service by the Knative route we created. It follows a format `<route-name>.<namespace>.<domain-suffix>`.
 
 [NOTE]
 ====

documentation/modules/ROOT/pages/04-scaling.adoc

@@ -356,7 +356,7 @@ We will now send some load to the greeter service.  The command below sends 50 c
 [source,bash,subs="+macros,+attributes",linenums]
 ----
 siege -r 1 -c 50 -t 30S \
-  -H "Host: greeter.knativetutorial.example.com" \
+  -H "Host:greeter.knativetutorial.example.com" \
   "http://pass:[${IP_ADDRESS}]"
 ----
 

documentation/modules/ROOT/pages/05-build/build-templates.adoc

@@ -209,7 +209,7 @@ include::ROOT:partial$invoke-service.adoc[tag=env]
 
 [source,bash,subs="+macros,+attributes",linenums]
 ----
-curl -H "Host: event-greeter.knativetutorial.example.com" $IP_ADDRESS \
+curl -H "Host:event-greeter.knativetutorial.example.com" $IP_ADDRESS \
    -H "Content-Type: application/json" \
    -d '{"message": "test message"}'
 ----
@@ -219,7 +219,7 @@ curl -H "Host: event-greeter.knativetutorial.example.com" $IP_ADDRESS \
 [source,bash,subs="+macros,+attributes",linenums]
 ----
 http POST $IP_ADDRESS \
-  'Host: event-greeter.knativetutorial.example.com'  \
+  'Host:event-greeter.knativetutorial.example.com'  \
    message="test message"
 ----
 

documentation/modules/ROOT/pages/05-build/build.adoc

@@ -306,7 +306,7 @@ include::ROOT:partial$invoke-service.adoc[tag=env]
 
 [source,bash,subs="+macros,+attributes",linenums]
 ----
-curl -H "Host: event-greeter.knativetutorial.example.com" $IP_ADDRESS \
+curl -H "Host:event-greeter.knativetutorial.example.com" $IP_ADDRESS \
    -H "Content-Type: application/json" \
    -d '{"message": "test message"}'
 ----
@@ -316,7 +316,7 @@ curl -H "Host: event-greeter.knativetutorial.example.com" $IP_ADDRESS \
 [source,bash,subs="+macros,+attributes",linenums]
 ----
 http POST $IP_ADDRESS \
-  'Host: event-greeter.knativetutorial.example.com'  \
+  'Host:event-greeter.knativetutorial.example.com'  \
    message="test message"
 ----
 

documentation/modules/ROOT/pages/_partials/invoke-service.adoc

@@ -11,13 +11,13 @@ IP_ADDRESS="$({k8s-env} ip):$({k8s-cli} get svc $INGRESSGATEWAY --namespace isti
 #tag::call[]
 [source,bash,subs="+macros,+attributes"]
 ----
-curl -v -H "Host: greeter.knativetutorial.example.com" $IP_ADDRESS 
+curl -v -H "Host:greeter.knativetutorial.example.com" $IP_ADDRESS
 ----
 
 .(OR)
 
 [source,bash,subs="+macros,+attributes"]
 ----
-http $IP_ADDRESS 'Host: greeter.knativetutorial.example.com'
+http $IP_ADDRESS 'Host:greeter.knativetutorial.example.com'
 ----
 #end::call[]

documentation/modules/ROOT/pages/faq.adoc

@@ -17,32 +17,31 @@ if kubectl get configmap config-istio -n knative-serving &> /dev/null; then
     INGRESSGATEWAY=istio-ingressgateway
 fi
 
-INGRESSGATEWAY=istio-ingressgateway
 IP_ADDRESS="$(minishift ip):$(kubectl get svc $INGRESSGATEWAY --namespace istio-system --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')"
 
 # calling a knative service named greeter
-curl -H "Host: greeter.knativetutorial.example.com" $IP_ADDRESS 
+curl -H "Host:greeter.knativetutorial.example.com" $IP_ADDRESS
 ----
 
 [#faq-q2]
 == Why `dev.local` suffixes for container images?
 
 .Tag Digest
 ***
-> Docker images wit v2 or later format has content addressable identifier called digest. The digest remains unchanged as long the underlying image content remains unchanged.
+> Docker images with v2 or later format have a content-addressable identifier called a `digest`. The digest is a hash of the image content, so images with the same digest are guaranteed to have idetical content.
 [.text-right]
 __**Source**: https://docs.docker.com/engine/reference/commandline/images/#list-image-digests__
 
 ***
 
-Let say you have a deployment like the following (note that resource definition have been trimmed for brevity):
+Given a deployment like the following (note that resource definitions have been trimmed for brevity):
 
 [source,yaml,linenums]
 ----
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-   name: helloworld 
+   name: helloworld
 spec:
   template:
     spec:
@@ -60,20 +59,19 @@ When you deploy this application in kubernetes, the deployment will look like:
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-   name: helloworld 
+   name: helloworld
 spec:
   template:
     spec:
        containers:
           - name: my-container
-            image: >-
-                   gcr.io/knative-samples/helloworld-go@sha256:98af362ceca8191277206b3b3854220ce125924b28a1166126296982e33882d0
+            image: gcr.io/knative-samples/helloworld-go@sha256:98af362ceca8191277206b3b3854220ce125924b28a1166126296982e33882d0
 . . .
 ----
 
-In the above example the container image name of the deployment  i.e. gcr.io/knative-samples/helloworld-go was resolved to its digest gcr.io/knative-samples/helloworld-go@sha256:98af362ceca8191277206b3b3854220ce125924b28a1166126296982e33882d0. Kubernetes extracts the digest from the image manifest.  This process of resolving  image tag to its digest is informally called as “Tag to Digest”.
+The container image name `gcr.io/knative-samples/helloworld-go` was resolved to its digest `gcr.io/knative-samples/helloworld-go@sha256:98af362ceca8191277206b3b3854220ce125924b28a1166126296982e33882d0`. Kubernetes extracts the digest from the image manifest.  This process of resolving  image tag to its digest is informally called as “Tag to Digest”.
 
-Knative Serving deployments by default resolve the container images to digest during the deployment process. Knative Serving has been configured to skip the resolution of   image name/tag to image digest for registries ko.local and dev.local, which can be used for local development builds, as the underlying image content are subject to changes during the  development process.
+Knative Serving deployments, by default, resolve the container images to digest during the deployment process. Knative Serving has been configured to skip the resolution of image name/tag to image digest for registries ko.local and dev.local, which can be used for local development builds where the underlying image contents are subject to change during the  development process.
 
 [TIP]
 ====
@@ -84,10 +82,10 @@ The following command shows an example how to add a registry **my.docker.registr
 ```
 val=$(oc -n knative-serving get cm config-controller -oyaml | yq r - data.registriesSkippingTagResolving | awk '{print $1",my.docker.registry"}')
 
-oc -n knative-serving get cm config-controller -oyaml | yq w - data.registriesSkippingTagResolving $val | oc apply -f - 
+oc -n knative-serving get cm config-controller -oyaml | yq w - data.registriesSkippingTagResolving $val | oc apply -f -
 ```
 ====
 
 [#faq-q3]
-== What is revision simpler terms?
-In Knative serving, things are driven via a https://github.com/knative/serving/blob/master/docs/spec/spec.md#configuration[Configuration] to make a separation between code (container images) and config. One of the good practices in configuration management is that we should always be able to rollback the application state to any “last known good configuration”, to be able to allow this type of rollback Knative creates an unique revision for each and every configuration change.
+== What is a "revision" in simpler terms?
+A https://github.com/knative/serving/blob/master/docs/spec/overview.md#revision[Revision] is an immutable snapshot of code and configuration. Each change to an application's https://github.com/knative/serving/blob/master/docs/spec/overview.md#configuration[Configuration] creates a new *Revision*, which allows an application to be rolled back to any previous “known good configuration”.

documentation/modules/ROOT/pages/index.adoc

@@ -1,6 +1,6 @@
 = Knative Tutorial
 
-Serverless epitomize the very benefits of what cloud platforms promise: offload the management of infrastructure while taking advantage of a consumption model for the actual utilization of services. While there are a number of server frameworks out there, Knative is the first serverless platform specifically designed for Kubernetes and OpenShift. 
+Serverless epitomizes the very benefits of what cloud platforms promise: offload the management of infrastructure while taking advantage of a consumption model for the actual utilization of services. While there are a number of serverless frameworks out there, Knative is the first specifically designed for Kubernetes and OpenShift.
 
 > Serverless computing refers to the concept of building and running applications that do not require server management. It describes a finer-grained deployment model where applications, bundled as one or more functions, are uploaded to a platform and then executed, scaled, and billed in response to the exact demand needed at the moment”
 
@@ -9,4 +9,4 @@ __**Source**__:  https://www.cncf.io/blog/2018/02/14/cncf-takes-first-step-towar
 
 This tutorial will act as a step-by-step guide in helping you understand Knative, starting with setup, fundamental concepts such as service, configuration, revision etc., and finally deploying some use cases which could help deploying serverless applications at enterprises.
 
-This content is brought to you by http://developers.redhat.com[Red Hat Developer Program] - Register today!
+This content is brought to you by http://developers.redhat.com[Red Hat Developer Program] - Register today!