diff --git a/doc/sphinx/source/data/new-commondata.rst b/doc/sphinx/source/data/new-commondata.rst
index 23ff31463c..3c7ef54408 100644
--- a/doc/sphinx/source/data/new-commondata.rst
+++ b/doc/sphinx/source/data/new-commondata.rst
@@ -15,7 +15,14 @@ Where all observables contained in one hepdata entry are separated by their obse
 Each folder will contain one single metadata file named ``metadata.yaml`` which defines all observables implemented for a given dataset.
 
 In order to keep backward compatibility and ease the comparison between new and old commondata, the ``buildmaster/dataset_names.yml`` file keeps a mapping of the datasets implemented in both formats.
-When a ``legacy`` variant is available, the usage of the old name automatically enables such variants.
+When a ``legacy`` variant is available, the usage of the old name automatically enables such variants. The format of this mapping is as follow (which enables using variants):
+
+..  code-block:: yaml
+
+    old_name_1: new_name_1
+    old_name_2:
+        dataset: new_name_2
+        variant: this_particular_variant
 
 
 Metadata Format
@@ -45,7 +52,7 @@ This ``metadata.yaml`` file contains a first portion of general information whic
         experiment: "EXPERIMENT_NAME"
 
     implemented_observables:
-    - observable_name: "OBS"
+      - observable_name: "OBS"
         observable:
             description: "Description of the observable"
             label: "Latex label for the observable"