diff --git a/src/python/PyBis/README.md b/src/python/PyBis/README.md
index b4db8bb03b8caf6dba85e80ce2473e86f8659e95..5e96b729ccfcb5fa37df6e0cd1292a4bdbfe2b24 100644
--- a/src/python/PyBis/README.md
+++ b/src/python/PyBis/README.md
@@ -290,7 +290,16 @@ tag.delete()
 
 ## Vocabualry and VocabularyTerms
 
-Vocabulary consists of many VocabularyTerms. They are used to control the Terms in a Property field. So for example, you want to add a property called **Animal** to a Sample and you want to control which terms are used in this Property. For this you need to do a couple of steps:
+An entity such as Sample (Object), Experiment (Collection), Material or DataSet can be of a specific type:
+
+* Sample Type
+* Experiment Type
+* DataSet Type
+* Material Type
+
+Every type defines which Properties may be defined. Properties are like Attributes, but they are Type specific. Properties can contain all sorts of information, such as free text, XML, Hyperlink, Boolean and also *Controlled Vocabulary*. Such a Controlled Vocabulary consists of many VocabularyTerms. They are used to check the terms entered in a Property field.
+
+So for example, you want to add a property called **Animal** to a Sample and you want to control which terms are entered in this Property field. For this you need to do a couple of steps:
 
 1. create a new vocabulary *AnimalVocabulary*
 2. add terms to that vocabulary: *Cat, Dog, Mouse*
@@ -357,4 +366,4 @@ This project is devided in several parts:
 - src/core-plugins/**jupyter-api**, an ingestion plug-in for openBIS, allowing people to upload new datasets
 - src/vagrant/**jupyter-bis/Vagrantfile** to set up JupyterHub on a virtual machine (CentOS 7), which uses the JupyterBis authenticator module
 - src/vagrant/**obis/Vagrantfile** to set up a complete OpenBIS instance on a virtual machine (CentOS 7)
-- 
\ No newline at end of file
+- 
diff --git a/src/python/PyBis/README.rst b/src/python/PyBis/README.rst
index 370e47122e47c61946362bc447fcdb086a06b928..5b1d275ca033ce2d722d0d2423d66ed2274dc0db 100644
--- a/src/python/PyBis/README.rst
+++ b/src/python/PyBis/README.rst
@@ -313,11 +313,24 @@ Tags
 Vocabualry and VocabularyTerms
 ------------------------------
 
-Vocabulary consists of many VocabularyTerms. They are used to control
-the Terms in a Property field. So for example, you want to add a
-property called **Animal** to a Sample and you want to control which
-terms are used in this Property. For this you need to do a couple of
-steps:
+An entity such as Sample (Object), Experiment (Collection), Material or
+DataSet can be of a specific type:
+
+-  Sample Type
+-  Experiment Type
+-  DataSet Type
+-  Material Type
+
+Every type defines which Properties may be defined. Properties are like
+Attributes, but they are Type specific. Properties can contain all sorts
+of information, such as free text, XML, Hyperlink, Boolean and also
+*Controlled Vocabulary*. Such a Controlled Vocabulary consists of many
+VocabularyTerms. They are used to check the terms entered in a Property
+field.
+
+So for example, you want to add a property called **Animal** to a Sample
+and you want to control which terms are entered in this Property field.
+For this you need to do a couple of steps:
 
 1. create a new vocabulary *AnimalVocabulary*
 2. add terms to that vocabulary: *Cat, Dog, Mouse*