Updated README and added a separate CONTRIBUTING guideline

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing
+
+Each test case must contain the following files:
+* A valid `*valid*.raml` file showcasing valid use of the feature under test
+* An invalid `*invalid*.raml` files showcasing invalid use of the feature under test
+
+and optionally:
+* Any number of Library and Fragment `.raml` files as well as `.json`, `.xml`, `.md`, and any other files in either the root folder or its subtree. These files must be used by the main valid/invalid `.raml` files.
+
+Test cases must be put under the `tests` directory by either putting your tests into an existing folder or creating a new one. Hereby, it is important that the folder name does reflect the main purpose and each file name should also be meaningful. For example, if you want to contribute a new test case that covers traits in RAML 1.0, you only need to create a new folder for your test case under `tests/raml-1.0/Traits` and copy your RAML files into that. 
+
+## Running tests
+
+We've created a separate project called [raml-tck-runner](https://github.com/raml-org/raml-tck-runner) to run all the tests contained in the RAML TCK. By following the instructions on that repository, you should be able to test any new test case that you may want to contribute against the different projects that this [raml-tck-runner](https://github.com/raml-org/raml-tck-runner) covers.

README.md

@@ -1,65 +1,27 @@
-# TCK - Test Compatibility Kit for RAML Parser
+# RAML TCK
 
-The Test Compatibility Kit (TCK) for the RAML Parser provides a way to separate the test resources from any parser implementation. TCK contains a set of RAML documents meant to be used to test correct/incorrect usage of each RAML feature. Note that only the failure or success to parse is tested, not the parsing outcome per sé.
+RAML's Test Compatibility Kit (RAML TCK) provides a way for any RAML processor to test its compliance with the RAML 1.0 Spec. RAML TCK contains a set of RAML documents meant to be used to test correct and incorrect usage of each RAML feature.
 
-# Naming convention
+## Naming convention
 
-*valid-\*.raml*: Valid RAML file parsing of which is expected to succeed.
+- `*valid*.raml`: valid RAML file expected to be successfully processed
+- `*invalid*.raml`: invalid RAML file with syntax/semantic/spec error(s), expected to be unsuccessfully processed (error or exit code returned)
 
-*\*invalid\*.raml*: Invalid RAML file that has syntax/semantic/spec errors. Parsing of it is expected to fail (parser errors/returns error/crashes).
+Note that this repository contains a [manifest file](./manifest.json) that lists all tests in the order their respective tested features appear in the RAML 1.0 Spec.
 
-Repository also contains a [manifest file](./manifest.json) that lists RAML files in the order features used in them are defined in RAML 1.0 spec.
+## Projects using this TCK
 
-# Run tests
-
-There are already few parsing tools that use the repo and test some parsers:
-
-**[raml-tck-runner](https://github.com/raml-org/raml-tck-runner)** tests parsers:
+Here are a few projects that have been tested against RAML TCK:
 * Go: [Jumpscale/go-raml](https://github.com/Jumpscale/go-raml), [go-raml/raml](https://github.com/go-raml/raml)
 * JavaScript: [raml-1-parser](https://github.com/raml-org/raml-js-parser-2), [amf-client-js](https://github.com/aml-org/amf), [webapi-parser](https://github.com/raml-org/webapi-parser)
 * Python: [ramlfications](https://github.com/spotify/ramlfications), [pyraml-parser](https://github.com/an2deg/pyraml-parser)
 * Ruby: [brujula](https://github.com/nogates/brujula), [raml-rb](https://github.com/jpb/raml-rb)
 * Java: [webapi-parser](https://github.com/raml-org/webapi-parser), [raml-java-parser](https://github.com/raml-org/raml-java-parser)
 
-Feel free to build more tools to fit your needs.
-
-# Contributing Tests
-
-We welcome any contributions from the community! You can contribute by sending us a pull request with your test cases. A test case, for example, should contain the following files:
-
-* Valid `.raml` file showcasing valid use of the feature under test
-* Invalid `.raml` files showcasing invalid use of the feature under test
-* Optionally, any number of Library and Fragment `.raml` files as well as `.json`, `.xml`, `.md`, and other files in either the root folder or its subtree. These files must be used by the main valid/invalid `.raml` files.
-
-Test cases must be put under the `tests` directory by either putting your tests into an existing folder or creating a new one. Hereby, it is important that the folder name does reflect the main purpose and each file name should also be meaningful. For example, if you want to contribute a new test case that covers traits in RAML 1.0, you only need to create a new folder for your test case under `tests/raml-1.0/Traits` and copy your RAML files into that. Please also make sure that you place additional metadata as comments into your RAML file to give more context about your test case. The following is a template:
-
-```
-<RAML_VERSION> <RAML_FRAGMENT>
-
-# Objective: <COMMENT>
-# Expected result: <COMMENT>
-
-# <COMMENT>
-
-# tags: <tag_1>, <tag_2>, ...,<tag_n>
-
-<RAML_CONTENT>
-```
-
-For more information, please have a look at [this example](tests/raml-1.0/spec-examples/APIs/additional-facets-single-example.raml).
-
-For more information what tags to use, please see a list of commonly used inside [common-tags.md](common-tags.md). You can suggest new by raising an issue within this repository.
-
-After adding new files make sure to regenerate the manifest file:
-
-Install dependencies:
+(Feel free to submit a PR to list any other tool that may be using the RAML TCK)
 
-```sh
-$ npm install
-```
+A compilation of the above project test results can be found on [this page](http://raml-org.github.io/raml-tck/). Those results have been generated using [raml-tck-runner](https://github.com/raml-org/raml-tck-runner).
 
-Generate the manifest:
+## Contributing
 
-```sh
-$ npm run-script gen-manifest
-```
+We welcome contributions! If you have a new test case in mind, feel free to submit a pull request. More info on how to do that [here](./CONTRIBUTING.md).