diff --git a/src/python/PyBis/README.rst b/src/python/PyBis/README.rst
index fce8582e92f51d9b1eef6f55132b1e24417a00c2..370e47122e47c61946362bc447fcdb086a06b928 100644
--- a/src/python/PyBis/README.rst
+++ b/src/python/PyBis/README.rst
@@ -310,6 +310,55 @@ Tags
     tag.get_samples()
     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:
+
+1. create a new vocabulary *AnimalVocabulary*
+2. add terms to that vocabulary: *Cat, Dog, Mouse*
+3. create a new PropertyType (e.g. *Animal*) of DataType
+   *CONTROLLEDVOCABULARY* and assign the *AnimalVocabulary* to it
+4. create a new SampleType (e.g. *Pet*) and *assign* the created
+   PropertyType to that Sample type.
+5. If you now create a new Sample of type *Pet* you will be able to add
+   a property *Animal* to it which only accepts the terms *Cat, Dog* or
+   *Mouse*.
+
+**create new Vocabulary with three VocabularyTerms**
+
+::
+
+    voc = o.new_vocabulary(
+        code = 'BBB',
+        description = 'description of vocabulary aaa',
+        urlTemplate = 'https://ethz.ch',
+        terms = [
+            { "code": 'term_code1', "label": "term_label1", "description": "term_description1"},
+            { "code": 'term_code2', "label": "term_label2", "description": "term_description2"},
+            { "code": 'term_code3', "label": "term_label3", "description": "term_description3"}
+        ]   
+    )
+    voc.save()
+
+**create additional VocabularyTerms**
+
+::
+
+    term = o.new_term(
+        code='TERM_CODE_XXX', 
+        vocabularyCode='BBB', 
+        label='here comes a label',
+        description='here is a meandingful description'
+    )
+    term.save()
+
+**fetching Vocabulary and VocabularyTerms**
+
 Requirements and organization
 =============================
 
diff --git a/src/python/PyBis/setup.py b/src/python/PyBis/setup.py
index e7131b1b928224d195f447e71cb8b30ccab07f9d..4472fb2f6d5112775d8349e5fafb8576f1431bc1 100644
--- a/src/python/PyBis/setup.py
+++ b/src/python/PyBis/setup.py
@@ -9,7 +9,7 @@ from setuptools import setup
 
 setup(
     name='PyBIS',
-    version= '1.6.3',
+    version= '1.6.4',
     description='openBIS connection and interaction, optimized for using with Jupyter',
     url='https://sissource.ethz.ch/sispub/pybis/',
     author='Swen Vermeul |  ID SIS | ETH Zürich',