Merge pull request #390 from SAP/mkdoc

updated docs

README.md

@@ -25,7 +25,7 @@ development descriptor (`mta.yaml` file) or from module build artifacts accordin
 ## Contributions
 
 Contributions are greatly appreciated.
-If you want to contribute, please follow [the guidelines](./.github/CONTRIBUTING.md).
+If you want to contribute, please follow [the guidelines](docs/docs/process.md).
 
 ## Support
 

docs/docs/index.md

@@ -26,10 +26,10 @@ Each module is built using the build technology that is either associated with t
 
 For more details about how the design-time module types in the `mta.yaml` file are converted into deployment time module types in the `mtad.yaml` file according to the target platform, see [Module types conversion](https://github.com/SAP/cloud-mta-build-tool/blob/master/configs/platform_cfg.yaml). 
 
-If the MTA Build Tool encounters a module type in the `mta.yaml` file that is not listed in the configuration file, its definition is copied to the `mtad.yaml` file as is and the `.zip` builder is applied to the module (in other words, the archived module sources are packaged as the build result).
+If the MTA Build Tool encounters a module type in the `mta.yaml` file that is not listed in the configuration file, its definition is copied to the `mtad.yaml` file as is and the `zip` builder is applied to the module (in other words, the archived module sources are packaged as the build result).
 
 All resource definitions are passed to the `mtad.yaml` file as is without mapping and validations (for example, if the resource is supported in the target platform or if the specified parameters match the type).
 
-###<b>Creating an MTA Archive According to the MTA Deploymnet Descriptor (`mtad.yaml` file)</b>
+### <b>Creating an MTA Archive According to the MTA Deploymnet Descriptor (`mtad.yaml` file)</b>
 
-TBD
+Under construction

docs/docs/migration.md

@@ -5,7 +5,7 @@ If you have previously used the [Multitarget Application Archive Builder](https:
 #### Features that handled differently in the Cloud MTA Build Tool
 
 * For building an MTA project, the Cloud MTA build Tool uses `GNU Make` technology. Therefore, you should have `GNU Make` installed in your build environmnet. Please read the correponding sections for more information about [`GNU Make` installation](makefile.md) and [commands for building a project](usage.md#how-to-build-an-mta-archive-from-the-project-sources). 
-<br>
+&nbsp;
 * Packaging of HTML5 modules in `deploy_mode=html5-repo`
 You need to update your `mta.yaml` file to exclude `html5` modules from the resulting MTA archive. In order to do that, add the following to the `build-parameters` section for each  module of this type:
 
@@ -14,21 +14,21 @@ You need to update your `mta.yaml` file to exclude `html5` modules from the resu
    build-parameters:
       supported-platforms: []
 ```
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; For more information about the `supported-platforms` build parameter, see [Configuring and Packaging Modules According to Target Platforms](configuration.md#configuring-and-packaging-modules-according-to-target-platforms)
-<br>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; For more information about the `supported-platforms` build parameter, see [Configuring and Packaging Modules According to Target Platforms](configuration.md#configuring-and-packaging-modules-according-to-target-platforms).
+&nbsp;
 * The following `build-parameters` are not supported by the Cloud MTA Build Tool: <ul><li>`npm-opts`<li>`grunt-opt`<li>`maven-opts`</ul>
 
-  If you need to change the default build behavior defined for the correponding builder, see [configure `custom` builder](configuration.md#configuring-the-custom-builder).
-  For a complete list of available builders and their default behaviors, see [Builders execution commands](https://github.com/SAP/cloud-mta-build-tool/blob/master/configs/builder_type_cfg.yaml).
-  <br>
+  If you need to change the default build behavior defined for the correponding builder, see [configure `custom` builder](configuration.md#configuring-the-custom-builder). For a complete list of available builders and their default behaviors, see [Builders execution commands](https://github.com/SAP/cloud-mta-build-tool/blob/master/configs/builder_type_cfg.yaml).
+  &nbsp;
 
 #### New features in the Cloud MTA Build Tool
 
-* If you want to run a builder process before running builders of the specific modules, define it using [global `before-all` build parameters](configuration.md#configuring-global-build).
-
-<br>
-* You can define your own build commands as described here: [configuring `custom` builder](configuration.md#configuring-the-custom-builder).
-<br>
+* In addition to configuring build behaviour in `mta.yaml`, you can configure build process of the specific module or the whole project in the `Makefile.mta` file that you can generate the file using [`mbt init` command](usage.md#cloud-mta-build-tool-commands). The generated file contains default configurations for buidling MTA project according to our best practices.
+&nbsp;&nbsp;
+* If you want to run a builder process before running builders of the specific modules, define it using [global `before-all` build parameters](configuration.md#configuring-global-build).  
+&nbsp; 
+* You can define your own build commands as described here: [configuring `custom` builder](configuration.md#configuring-the-custom-builder). 
+&nbsp; 
 
 #### Features that are temporarily not available in the Cloud MTA Build Tool
 

docs/docs/usage.md

@@ -4,23 +4,23 @@
 | Command | Usage                                | Description                                                    
 | ------  | --------       |  ----------                                                
 | help    | `mbt -h`     | Prints all the available commands.                           
-| help    | `mbt [command] --help` or<br> `mbt [command] -h`    | Prints detailed information on the selected command.                           
-<br>
+| help    | `mbt [command] --help` or<br> `mbt [command] -h`    | Prints detailed information about the specified command.|
 
-### How to display the current tool version
+&nbsp;
+### How to find out the installed tool version
 
 | Command | Usage &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;       | Description                                                    
 | ------  | --------       |  ----------                                                
-| version | `mbt -v`     | Prints the current Cloud MTA Build Tool version.                                        |
-<br>
+| version | `mbt -v`     | Prints the current Cloud MTA Build Tool version.                                        <br>
 
+&nbsp;
 ### How to build an MTA archive from the project sources
 
 #### Prerequisites
 * `GNU Make 4.2.1` is installed in your build environment. 
 * Module build tools are installed in your build environment.
 
-For more information, see the corresponding `Download` and `Installation` sections.
+For more information, see the corresponding [`Download` and `Installation` sections](download.md).
 
 #### Quick start example
 
@@ -58,7 +58,7 @@ Use the `make` command to package the MTA project with the following parameters:
 | `mtar`    | string     |   Optional  | The file name of the generated archive file. If this parameter is omitted, the file name is created according to the following naming convention: <br><br> `<mta_application_ID>_<mta_application_version>.mtar` <br><br> If the parameter is provided, but does not include an extension, the `.mtar` extension is added. | `make -f Makefile.mta p=cf mtar=myMta`<br><br> `make -f Makefile.mta p=cf mtar=myMta.mtar`
 | `strict`    | Boolean     | Optional    | The default value is `true`. If set to `true`, the duplicated fields and fields that are not defined in the `mta.yaml` schema are reported as errors. If set to `false`, they are reported as warnings. | `make -f Makefile.mta p=cf strict=false`
 
-<br>
+&nbsp;
 ### How to build an MTA archive from the modules' build artifacts 
 
 | Command | Usage &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;       | Description