Kyma CLI inline documentation review (#91)

README.md

@@ -2,77 +2,103 @@
 
 ## Overview
 
-A command line tool to support developers of and with [Kyma](https://github.com/kyma-project/kyma)
-
-## Available Commands
-
-- `version`: Shows the Kyma cluster version and the Kyma CLI version
-- `provision minikube`: Initializes minikube with a new cluster (replaces the `minikube.sh` script) 
-- `install`: Installs Kyma to a cluster based on a release (replaces the `ìnstaller.sh` and `is-installed.sh` script)
-- `uninstall`: Uninstalls all Kyma related resources from a cluster
-- `completion`: Outputs shell completion code for bash
-- `test`: Triggers and reports the tests for every Kyma module
-- `help`: Displays usage for the given command (e.g. `kyma help`, `kyma help status`, etc...)
+Kyma CLI is a command line tool which supports [Kyma](https://github.com/kyma-project/kyma) developers. It provides a set of commands you can use to install and test Kyma. 
 
 ## Prerequisites
 
-In order to run the Kyma CLI you need the following software installed:
+Kyma CLI requires the following software:
 - [kubectl](https://github.com/kubernetes/kubectl) 
-- [minikube](https://github.com/kubernetes/minikube) 
+- [Minikube](https://github.com/kubernetes/minikube) 
+
+## Installation
+
+For the installation instructions, see the [release page](https://github.com/kyma-project/cli/releases).
 
 ## Usage
 
-Installation of Kyma with minikube on Mac:
+### Commands
 
-```bash
-kyma provision minikube
-kyma install
-```
+Kyma CLI comes with a set of commands:
 
-Installation of Kyma with minikube on Windows:
+- `version` shows the Kyma cluster version and the Kyma CLI version.
+- `provision minikube` initializes Minikube on a new cluster. It replaces the `minikube.sh` script. 
+- `install` installs Kyma to a cluster based on the current release. It replaces the `ìnstaller.sh` and `is-installed.sh` script. 
+- `uninstall` uninstalls all Kyma-related resources from a cluster.
+- `completion` generates and shows the bash completion script.
+- `test` triggers and reports the tests for every Kyma module.
+- `help` displays and explains the usage of a given command.
 
-```bash
-kyma provision minikube
-# follow instructions to add hosts
-kyma install
-```
 
-Installation of Kyma with minikube on Windows using HyperV:
+### Use Kyma CLI
 
-```bash
-kyma provision minikube --vm-driver hyperv --hypervVirtualSwitch {YOUR_SWITCH_NAME}
-# follow instructions to add hosts
-kyma install
+Use the following syntax to run the commands from your terminal:
+
+```
+kyma {COMMAND} {FLAGS}
 ```
+where:
+
+* **{COMMAND}** specifies the operation you want to perform.
+* **{FLAGS}** specify optional flags. For example, use `-v` or `--verbose` for additional information on performed operations.
+
+Example:
 
-Run tests on Kyma installation:
-```bash
-kyma test
 ```
-## Installation
+kyma install --verbose
+```
+
+Further usage examples include:
+
+* Install Kyma with Minikube on Mac:
+
+    ```bash
+    kyma provision minikube
+    kyma install
+    ```
+
+* Install Kyma with Minikube on Windows:
+
+    ```bash
+    kyma provision minikube
+    # follow instructions to add hosts
+    kyma install
+    ```
+
+* Install Kyma with Minikube on Windows using HyperV:
+
+    ```bash
+    kyma provision minikube --vm-driver hyperv --hypervVirtualSwitch {YOUR_SWITCH_NAME}
+    # follow instructions to add hosts
+    kyma install
+    ```
+
+ * Run tests on Kyma:
+    ```bash
+    kyma test
+    ```
 
-For the latest release and installation instructions, see the [release page](https://github.com/kyma-project/cli/releases)
+## Development
 
-## Kyma CLI as a Kubectl plugin
+### Kyma CLI as a kubectl plugin
 
-To follow this section a kubectl version of 1.12.0 or later is required.
+> **NOTE**: To use Kyma CLI as a kubectl plugin, use Kubernetes version 1.12.0 or higher.
 
-A plugin is nothing more than a standalone executable file, whose name begins with kubectl- . To install a plugin, simply move this executable file to anywhere on your PATH.
+A plugin is a standalone executable file with a name prefixed with `kubectl-` .To use the plugin, perform the following steps:
 
-Rename a `kyma` binary to `kubectl-kyma` and place it anywhere in your PATH:
+1. Rename the `kyma` binary to `kubectl-kyma` and place it anywhere in your **{PATH}**:
 
 ```bash
 sudo mv ./kyma /usr/local/bin/kubectl-kyma
 ```
 
-Run `kubectl plugin list` command and you will see your plugin in the list of available plugins.
+2. Run `kubectl plugin list` command to see your plugin on the list of all available plugins.
 
-You may now invoke your plugin as a kubectl command:
+3. Invoke your plugin as a kubectl command:
 
 ```bash
 $ kubectl kyma version
 Kyma CLI version: v0.6.1
 Kyma cluster version: 1.0.0
 ```
 
-To know more about extending kubectl with plugins read [kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/).
+For more information on extending kubectl with plugins, read [Kubernetes documentation](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/).

internal/kubectl/kubectl.go

@@ -62,7 +62,7 @@ func execCmd(cmd *exec.Cmd, inputText string, verbose bool) (string, error) {
 		if verbose {
 			fmt.Printf("\nExecuted command:\n  kubectl %s\nwith output:\n  %s\nand error:\n  %s\n", inputText, string(out), err)
 		}
-		return unquotedOut, fmt.Errorf("Failed executing kubectl command 'kubectl %s' with output '%s' and error message '%s'", inputText, out, err)
+		return unquotedOut, fmt.Errorf("Failed executing kubectl 'kubectl %s' command  with output '%s' and error message '%s'", inputText, out, err)
 	}
 	if verbose {
 		fmt.Printf("\nExecuted command:\n  kubectl %s\nwith output:\n  %s\n", inputText, string(out))
@@ -177,7 +177,7 @@ func IsPodReady(namespace string, labelName string, labelValue string, verbose b
 		if containerStatus != "true" {
 			events, err := RunCmd(verbose, "get", "event", "-n", namespace, "-o", "go-template='{{range .items}}{{if eq .involvedObject.name \"'"+pod+"'\"}}{{.message}}{{\"\\n\"}}{{end}}{{end}}'")
 			if err != nil {
-				fmt.Printf("Error while checking for pod events '%s'\n‚", err)
+				fmt.Printf("Error occurred while searching for Pod Events '%s'\n‚", err)
 			}
 			if events != "" {
 				fmt.Printf("Status '%s'", events)
@@ -213,5 +213,5 @@ func CheckVersion(verbose bool) (string, error) {
 		return "", nil
 	}
 
-	return fmt.Sprintf("You are using an unsupported kubectl version '%s'. This may not work. It is recommended to use kubectl version '%s'", version, kubectlVersion), nil
+	return fmt.Sprintf("You are using an unsupported kubectl version '%s'. This may not work. The recommended kubectl version is '%s'", version, kubectlVersion), nil
 }

internal/minikube/minikube.go

@@ -25,7 +25,7 @@ func RunCmd(verbose bool, args ...string) (string, error) {
 		if verbose {
 			fmt.Printf("\nExecuted command:\n  minikube %s\nwith output:\n  %s\nand error:\n  %s\n", strings.Join(args, " "), string(out), err)
 		}
-		return unquotedOut, fmt.Errorf("Failed executing command 'minikube %s' with output '%s' and error message '%s'", strings.Join(args, " "), out, err)
+		return unquotedOut, fmt.Errorf("Failed executing the 'minikube %s' command with output '%s' and error message '%s'", strings.Join(args, " "), out, err)
 	}
 	if verbose {
 		fmt.Printf("\nExecuted command:\n  minikube %s\nwith output:\n  %s\n", strings.Join(args, " "), string(out))
@@ -57,7 +57,7 @@ func CheckVersion(verbose bool) (string, error) {
 	if check {
 		return "", nil
 	}
-	return fmt.Sprintf("You are using an unsupported minikube version '%s'. This may not work. It is recommended to use minikube version '%s'", version, minikubeVersion), nil
+	return fmt.Sprintf("You are using an unsupported Minikube version '%s'. This may not work. The recommended Minikube version is '%s'", version, minikubeVersion), nil
 }
 
 //DockerClient creates a docker client based on minikube "docker-env" configuration