Merge pull request #48 from cap-js/smaller-ord-documentation-updates

Smaller suggestions for ORD.md documentation update

README.md

@@ -4,9 +4,11 @@
 
 ## About this project
 
-This plugin enables generation of ORD document for CAP based applications. When you adopt ORD, your application gains a single entry point, known as the Service Provider Interface. This interface allows you to discover and gather relevant information or metadata. You can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system landscapes.
+This plugin adds support for the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) (ORD) protocol for CAP based applications. 
+When you add the ORD plugin, your application gains a single entry point, which allows to discover and gather machine-readable information or metadata about the application. 
+You can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system instances / system landscapes.
 
-Open Resource Discovery [(ORD)](https://sap.github.io/open-resource-discovery/) is a protocol that enables applications and services to self-describe their available resources and capabilities. It's not only useful for describing static documentation, but it also accurately reflects tenant-specific configurations and extensions at runtime. Typically, ORD is used to describe APIs and Events, but it also supports higher-level concepts like Entity Types (Business Objects) and Data Products (beta).
+For more information, have a look at the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) page. 
 
 ## Requirements and Setup
 
@@ -50,7 +52,6 @@ cds compile <path to srv folder> --to ord [-o] [destinationFilePath]
 
 You can find more information, such as how to customize the ORD Document, in this [document](ord.md).
 
-
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/ord/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).

ord.md

@@ -2,22 +2,22 @@
 
 The cap-js ORD plugin has a default behavior where all the values of the ORD document are generated automatically by the plugin without the user giving them explicitly.
 
-If this default behavior is to be overwritten , then there are two ways in which it could be done.
+If this default behavior is to be overwritten, then there are two ways in which it could be done.
 
-For all the application level felids it is done using `present configuration` ( in `./cdsrc.json` under `ord` section).
+For all the application global information, it can be done using `present configuration` ( in `./cdsrc.json` under `ord` section).
 
 Example:
 
 ```js
- "ord": {
-        "namespace": "sap.sample",
-        "description": "this is my custom description",
-        "policyLevel": "sap:core:v1"
-    }
-
+// cdsrc.json or package.json cds context
+  "ord": {
+    "namespace": "sap.sample",
+    "description": "this is my custom description",
+    "policyLevel": "sap:core:v1"
+  }
 ```
 
-For all the service level felids it is done using annotations ( in the `.cds` files as `@ORD.Extensions`).
+For all the service level information, they can be added / overwritten using annotations (in the `.cds` files as `@ORD.Extensions`).
 
 Example:
 
@@ -34,11 +34,12 @@ annotate ProcessorService with @ORD.Extensions : {
 ```
 
 Also note that annotations like `@Core.Description` and `@description` are also read.
-The overwriting happens in the following priority : ord.extensions annotations > cap annotations > defaults.
+
+The overwriting happens in the following priority: ord.extensions annotations > cap annotations > defaults.
 
 The below is the table for all the supported ORD Fields containing defaults and how to overwrite the same.
 
-Note: `namespace` is usually taken from `.cdsrc.json` if not we take the `package.json` name. 
+Note: `namespace` is usually taken from `.cdsrc.json`, with a fallback to the `package.json` name. 
 
 | ORD Field  | Type | Defaults | Preset/Annotation | Usage Example | Description |
 |----------|----------|----------|----------|----------|----------|