diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md
index e69de29..3bef333 100644
--- a/docs/GLOSSARY.md
+++ b/docs/GLOSSARY.md
@@ -0,0 +1,2 @@
+# XOS-TOSCA Glossary
+
diff --git a/docs/README.md b/docs/README.md
index 2d0c6e4..39e033c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,39 +1,36 @@
 # TOSCA Interface
 
-A TOSCA interface is available for configuring and controlling CORD. It is 
-auto-generated from the set of [models](../xos/README.md) configured 
-into the POD manifest, and includes both core and service-specific models.
+A TOSCA interface is available for configuring and controlling CORD. It is
+auto-generated from the set of [models](../xos/README.md) configured into the
+POD manifest, and includes both core and service-specific models.
 
->In `CORD-4.0` this `TOSCA` interface is released as an `alpha` feature.
+> NOTE: In `CORD-4.0` this `TOSCA` interface is released as an `alpha` feature.
 
 ## What is TOSCA?
 
-Topology and Orchestration Specification for Cloud Applications
-(TOSCA) is an OASIS standard language to describe a topology of cloud
-based web services, their components, relationships, and the processes
-that manage them. The TOSCA standard includes specifications to
-describe processes that create or modify web services. You can read
-more about it on the
+Topology and Orchestration Specification for Cloud Applications (TOSCA) is an
+OASIS standard language to describe a topology of cloud based web services,
+their components, relationships, and the processes that manage them. The TOSCA
+standard includes specifications to describe processes that create or modify
+web services. You can read more about it on the
 [OASIS](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=tosca)
 website.
 
-CORD extends the TOSCA specification to support custom models for
-services, allow operators to manage them with a simple and well-known
-YAML interface.
+CORD extends the TOSCA specification to support custom models for services,
+allow operators to manage them with a simple and well-known YAML interface.
 
 ## Internals
 
-The `xos-tosca` container autogenerates the TOSCA interface starting
-from the `xproto` definition.  When the `xos-tosca` container starts,
-it connects to `xos-core`
-via the `gRPC` API to fetch all the `xproto` definition of the
-onboarded models. This includes both `core` and `service` models.
-Then using the `xos-genx` toolchain, it will generates the
-corresponding TOSCA specifications.
+The `xos-tosca` container autogenerates the TOSCA interface starting from the
+`xproto` definition.  When the `xos-tosca` container starts, it connects to
+`xos-core` via the `gRPC` API to fetch all the `xproto` definition of the
+onboarded models. This includes both `core` and `service` models.  Then using
+the `xos-genx` toolchain, it will generates the corresponding TOSCA
+specifications.
 
 For example, the `xproto` definition of a compute node in `XOS` is:
 
-```
+```protobuf
 message Node::node_policy (XOSBase) {
      required string name = 1 [max_length = 200, content_type = "stripped", blank = False, help_text = "Name of the Node", null = False, db_index = False];
      required manytoone site_deployment->SiteDeployment:nodes = 2 [db_index = True, null = False, blank = False];
@@ -42,7 +39,7 @@
 
 which is then transformed in the following TOSCA spec:
 
-```
+```yaml
 tosca_definitions_version: tosca_simple_yaml_1_0
 
 node_types:
@@ -62,12 +59,12 @@
                 type: string
                 required: false
                 description: "Name of the Node"
-            
+
 
     tosca.relationships.BelongsToOne:
         derived_from: tosca.relationships.Root
         valid_target_types: [ tosca.capabilities.xos.SiteDeployment ]
-    
+
 
     tosca.capabilities.xos.Node:
         derived_from: tosca.capabilities.Root
@@ -83,7 +80,7 @@
 Once CORD is up and running, a `node` can be added to a POD
 using the TOSCA interface by uploading the following recipe:
 
-```
+```yaml
 tosca_definitions_version: tosca_simple_yaml_1_0
 
 description: Load a compute node in XOS
@@ -106,12 +103,14 @@
 ### Where to find the generated specs?
 
 On any running CORD POD, the TOSCA apis are accessible as:
-```
+
+```shell
 curl http://<head-node-ip>:<head-node-port>/xos-tosca | python -m json.tool
 ```
 
 And it will return a list of all the recipes with the related url:
-```
+
+```json
 {
   "image": "/custom_type/image",
   "site": "/custom_type/site",
@@ -120,7 +119,8 @@
 ```
 
 For examples, to site the TOSCA spec of the Site model, you can use the URL:
-```
+
+```shell
 curl http://<head-node-ip>:<head-node-port>/xos-tosca/custom_type/site
 ```
 
@@ -128,12 +128,14 @@
 
 The `xos-tosca` container exposes two endpoint:
 
-```
+```shell
 POST http://<head-node-ip>:<head-node-port>/xos-tosca/run
 POST http://<head-node-ip>:<head-node-port>/xos-tosca/delete
 ```
 
 To load a recipe via `curl` you can use this command:
-```
+
+```shell
 curl -H "xos-username: xosadmin@opencord.org" -H "xos-password: <xos-password>" -X POST --data-binary @<path/to/file> http://<head-node-ip>:<head-node-port>/xos-tosca//run
 ```
+
diff --git a/docs/devel.md b/docs/devel.md
index 4a7f752..7586f3c 100644
--- a/docs/devel.md
+++ b/docs/devel.md
@@ -1,21 +1,26 @@
 # Development
 
 To run a development environment locally, you'll need to have:
-- an XOS configuration running in the frontend vm
-- source the xos virtual env (from `xos` root: `source scripts/setup_venv.sh`)
-- install `xos-tosca` specific dependencies: `pip install -r pip_requirements.txt`
-- an entry in the `/etc/hosts` file that point `xos-core.opencord.org` to you local environment
 
-### Run the xos-tosca process
+* an XOS configuration running in the frontend vm
+* source the xos virtual env (from `xos` root: `source scripts/setup_venv.sh`)
+* install `xos-tosca` specific dependencies: `pip install -r
+  pip_requirements.txt`
+* an entry in the `/etc/hosts` file that point `xos-core.opencord.org` to you
+  local environment
+
+## Run the xos-tosca process
 
 You can run this either from an IDE or:
+
 ```bash
 python scr/main.py
 ```
 
-### Sample call
+## Sample call
 
 To send an example request to `xos-tosca`:
+
 ```bash
 curl -X POST --data-binary @test.yaml 127.0.0.1:9200
 ```