diff --git a/doc/source/index.rst b/doc/source/index.rst
index c876076a5..32c41e5cc 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -74,6 +74,7 @@ User Guide
    user/vnf_component_usage_guide.rst
    user/enhanced_placement_awareness_usage_guide.rst
    reference/mistral_workflows_usage_guide.rst
+   reference/block_storage_usage_guide.rst
 
 API Documentation
 =================
diff --git a/doc/source/devref/block_storage_usage_guide.rst b/doc/source/reference/block_storage_usage_guide.rst
similarity index 97%
rename from doc/source/devref/block_storage_usage_guide.rst
rename to doc/source/reference/block_storage_usage_guide.rst
index b7e1f9f4b..4fb56f824 100644
--- a/doc/source/devref/block_storage_usage_guide.rst
+++ b/doc/source/reference/block_storage_usage_guide.rst
@@ -40,7 +40,7 @@ Create Volume
 
 To add volume, we need to add the below node to the VNFD:
 
-::
+.. code-block:: yaml
 
   VB1:
     type: tosca.nodes.BlockStorage.Tacker
@@ -51,7 +51,7 @@ Attach volume to VDU
 ~~~~~~~~~~~~~~~~~~~~
 Next attach the created volume to VDU as below:
 
-::
+.. code-block:: yaml
 
   CB1:
     type: tosca.nodes.BlockStorageAttachment
@@ -65,7 +65,8 @@ Next attach the created volume to VDU as below:
 
 With these additions, the new VNFD looks like below:
 
-::
+.. code-block:: yaml
+
   tosca_definitions_version: tosca_simple_profile_for_nfv_1_0_0
   description: Demo example
 
@@ -77,25 +78,21 @@ With these additions, the new VNFD looks like below:
       VDU1:
         type: tosca.nodes.nfv.VDU.Tacker
         capabilities:
-
           nfv_compute:
             properties:
               num_cpus: 1
               mem_size: 512 MB
               disk_size: 1 GB
-
         properties:
           image: cirros-0.3.5-x86_64-disk
           availability_zone: nova
           mgmt_driver: noop
-
           config: |
             param0: key1
             param1: key2
 
       CP1:
         type: tosca.nodes.nfv.CP.Tacker
-
         properties:
           management: true
           order: 0
@@ -108,16 +105,13 @@ With these additions, the new VNFD looks like below:
 
       VB1:
         type: tosca.nodes.BlockStorage.Tacker
-
         properties:
           size: 1 GB
 
       CB1:
         type: tosca.nodes.BlockStorageAttachment
-
         properties:
           location: /dev/vdb
-
           requirements:
             - virtualBinding:
                 node: VDU1
@@ -126,7 +120,6 @@ With these additions, the new VNFD looks like below:
 
       VL1:
         type: tosca.nodes.nfv.VL
-
         properties:
           network_name: net_mgmt
           vendor: Tacker