tweak README

Author: jstoiko

.gitignore

@@ -76,13 +76,11 @@ classes
 # Ignore generated JS and .jar
 /js/module/webapi-parser.js
 /examples/java/libs/*.jar
-
-# Fat jar
-./*.jar
+webapi-parser-*.jar
 
 # Files generated by examples
-generated.raml
-generated.json
+examples/*/generated.raml
+examples/*/generated.json
 
 # Generated docs
-docs/
+docs/

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+## Contribution Guidelines
+
+### Contributor Agreement
+
+To contribute source code to this repository, please read our [Contributor Agreement](http://www.mulesoft.org/legal/contributor-agreement.html), and then execute it by running [this notebook](https://api-notebook.anypoint.mulesoft.com/notebooks/#380297ed0e474010ff43) and following the instructions.
+
+## Setting-up this project locally
+
+### Requirements
+* Scala 2.12.2
+* sbt 0.13.15
+
+### Generate artifacts
+To generate JavaScript artifact (generated at `./js/module/webapi-parser.js`), run:
+```sh
+sbt buildJS
+```
+
+To generate regular (not "fat") `.jar`, run:
+```sh
+sbt package
+```
+
+To generate a "fat" `.jar` (generated at `./webapi-parser-X.Y.Z.jar`), run:
+```sh
+sbt assembleFatJar
+```
+and then you can copy/move that JAR to your `libs` directory and depend on it directly:
+
+```groovy
+dependencies {
+    compile files('libs/webapi-parser-X.Y.Z.jar')
+}
+```
+
+## Running tests
+```sh
+sbt test
+```

README.md

@@ -1,35 +1,38 @@
 # webapi-parser
-API Spec parser based on AMF. Supports OAS 2.0, and RAML 0.8, 1.0.
+API Spec parser based on [AMF](https://github.com/aml-org/amf). Currently supports RAML 0.8, 1.0 and OAS 2.0. 
 
-## API documentation
-[JavaScript API](https://raml-org.github.io/webapi-parser/js/modules/_webapi_parser_.html)
+This project is a thin wrapper that exposes API Spec-related capabilities from [AMF](https://github.com/aml-org/amf). It is written in Scala and offered in two versions: [JavaScript](#javascript) and [Java](#java).
 
-[Java API](https://raml-org.github.io/webapi-parser/java/index.html)
+## JavaScript
 
-[AMF Model API](https://raml-org.github.io/webapi-parser/js/classes/_amf_client_js_.model.document.baseunit.html)
+### Documentation
+* [JavaScript API](https://raml-org.github.io/webapi-parser/js/modules/_webapi_parser_.html)
+* [AMF Model](https://raml-org.github.io/webapi-parser/js/classes/_amf_client_js_.model.document.baseunit.html)
 
-## Installation
-
-### JS
-Install npm package with
+### Installation
+Install the npm package:
 
 ```sh
 $ npm install webapi-parser
 ```
 
-Start using it with
-
+and then require/reference as follows:
 ```js
 const wap = require('webapi-parser').WebApiParser
 ```
 
-Check [JS examples directory](examples/js/) for more usage examples.
+You can check the [JavaScript examples directory](examples/js/) for some usage examples.
+
+## Java
 
-### Java
-To use, specify `webapi-parser` dependency.
+### Documentation
+* [Java API](https://raml-org.github.io/webapi-parser/java/index.html)
+* [AMF Model](https://raml-org.github.io/webapi-parser/js/classes/_amf_client_js_.model.document.baseunit.html)
 
-Gradle example:
+### Installation
+To use, you'll need to specify `webapi-parser` as a dependency and set both MuleSoft and Jitpack repositories.
 
+Gradle:
 ```groovy
 dependencies {
     compile 'org.raml:webapi-parser_2.12:x.y.z'
@@ -46,8 +49,7 @@ repositories {
 }
 ```
 
-Maven example:
-
+Maven:
 ```xml
 <dependency>
     <groupId>org.raml</groupId>
@@ -67,39 +69,7 @@ Maven example:
 </repositories>
 ```
 
-To use locally built "fat" jar, copy it to your `libs` directory and depend on it like so
-
-```groovy
-dependencies {
-    compile files('libs/webapi-parser-X.Y.Z.jar')
-}
-```
-
-Check [Java examples directory](examples/java/) for more usage examples.
-
-
-## Generate artifacts directly from cloned repository
-
-### Requirements
-* Scala 2.12.2
-* sbt 0.13.15
-
-### Generate JS artifact
-To generate JS artifact to `./js/module/webapi-parser.js` run
-
-```sh
-sbt buildJS
-```
-
-### Generate Java artifact
-To generate regular (not "fat") `.jar` run
+You can check the [Java examples directory](examples/java/) for some usage examples.
 
-```sh
-sbt package
-```
-
-To generate "fat" `.jar` to `./webapi-parser-X.Y.Z.jar` run
-
-```sh
-sbt assembleFatJar
-```
+---
+If you wish to contribute to this project, see our [Contribution Guidelines](./CONTRIBUTING.md).

examples/java/README.md

@@ -1,11 +1,10 @@
 ## About
-This code aims to provide some usage examples to learn how to use `webapi-parser` in Java projects.
+This code provides some examples of how to use `webapi-parser` in Java projects.
 
 ## Installation
-Please follow `webapi-parser` [Java installation instructions](../../README.md#java).
+See [Java installation instructions](../../README.md#java).
 
 Build project and install dependencies:
-
 ```sh
 $ ./gradlew build
 ```

examples/js/README.md

@@ -1,14 +1,11 @@
 ## About
-This code aims to provide some usage examples to learn how to use `webapi-parser` in JS projects.
-
-Each file contains example of parsing, generation, validation and/or resolving of different WebApi formats.
+This folder provides some examples of how to use `webapi-parser` in JavaScript projects. Those examples showcase: parsing, generation, validation and/or resolving of different WebApi formats.
 
 ## Installation
-Please follow `webapi-parser` [JS installation instructions](../../README.md#js).
+See [JavaScript installation instructions](../../README.md#javascript).
 
 ## How to run
-Run desired script with `node <script_name>.js`. E.g.
-
+Run any script with `node <script_name>.js`. E.g.
 ```sh
 $ node raml10-string.js
 ```