added more description controlled vocabulary

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

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*