diff --git a/README b/README
index 14730b5d04..e574ae8c49 100644
--- a/README
+++ b/README
@@ -3,7 +3,8 @@ IfcOpenShell
 open source (LGPL) software library for working with the IFC file format
 
 
-http://IfcOpenShell.org
+http://ifcopenshell.org
+http://academy.ifcopenshell.org
 
 
 Compiling on Windows
@@ -25,9 +26,8 @@ environment variable. Python needs to be installed, please provide the
 include and library paths to Visual Studio.
 
 
-
 Compiling on *nix
-====================
+=================
 Users are advised to build IfcOpenShell using the cmake file provided in
 the cmake/ folder. There might be an Open CASCADE package in your operating
 system's software repository. If not, you will need to compile Open 
@@ -36,30 +36,83 @@ CASCADE yourself. See http://opencascade.org.
 For building the IfcPython wrapper, SWIG and Python development are
 required.
 
+Additionally, on Ubuntu (and possibly other linux flavors) the following steps
+install some of the prerequisites:
+
+    $ sudo apt-get install git swig cmake gcc g++ libftgl-dev libtbb2 libtbb-dev libboost-all-dev libgl1-mesa-dev libfreetype6-dev
+    $ git clone https://github.com/tpaviot/oce.git
+    $ cd oce
+    $ mkdir build && cd build
+    $ cmake ..
+    $ make
+    $ sudo make install   
+
 To build IfcOpenShell please take the following steps:
-$ cd /path/to/IfcOpenShell/cmake
-$ mkdir build
-$ cd build
-Optionally:
-  $ OCC_INCLUDE_PATH="/path/to/OpenCASCADE/include"
-  $ OCC_LIBRARY_PATH="/path/to/OpenCASCADE/lib"
-  $ export OCC_INCLUDE_PATH
-  $ export OCC_LIBRARY_PATH
-$ cmake ../
-$ make
+
+    $ cd /path/to/IfcOpenShell/cmake
+    $ mkdir build
+    $ cd build
+    Optionally:
+        $ OCC_INCLUDE_PATH="/path/to/OpenCASCADE/include"
+        $ OCC_LIBRARY_PATH="/path/to/OpenCASCADE/lib"
+        $ export OCC_INCLUDE_PATH
+        $ export OCC_LIBRARY_PATH
+    $ cmake ../
+    $ make
 
 If all worked out correctly you can now use IfcOpenShell. For example:
-$ wget ftp://ftp.dds.no/pub/ifc/Munkerud/Munkerud_hus6_BE.zip
-$ unzip Munkerud_hus6_BE.zip
-$ ./IfcObj Munkerud_hus6_BE.ifc
-$ less Munkerud_hus6_BE.obj
-Or:
-$ wget ftp://ftp.dds.no/pub/ifc/Munkerud/Munkerud_hus6_BE.zip
-$ unzip Munkerud_hus6_BE.zip
-$ python
->>> import IfcImport
->>> IfcImport.Init('Munkerud_hus6_BE.ifc')
->>> geom = IfcImport.Get()
->>> geom.name
->>> for v in geom.mesh.verts: v
 
+    $ wget ftp://ftp.dds.no/pub/ifc/Munkerud/Munkerud_hus6_BE.zip
+    $ unzip Munkerud_hus6_BE.zip
+    $ ./IfcConvert Munkerud_hus6_BE.ifc
+    $ less Munkerud_hus6_BE.obj
+
+Or:
+
+    $ wget ftp://ftp.dds.no/pub/ifc/Munkerud/Munkerud_hus6_BE.zip
+    $ unzip Munkerud_hus6_BE.zip
+    $ python
+    >>> import ifcopenshell
+    >>> f = ifcopenshell.open("Duplex_A_20110907_optimized.ifc")
+    >>> f.by_type("ifcwall")[:2]
+    [#91=IfcWallStandardCase('2O2Fr$t4X7Zf8NOew3FL9r',#1,'Basic Wall:Interior - Partition (92mm Stud):144586',$,'Basic Wall:Interior - Partition (92mm Stud):128360',#5198,#18806,'144586'), #92=IfcWallStandardCase('2O2Fr$t4X7Zf8NOew3FLIE',#1,'Basic Wall:Interior - Partition (92mm Stud):143921',$,'Basic Wall:Interior - Partition (92mm Stud):128360',#5206,#18805,'143921')]
+    >>> wall = _[0]
+    >>> len(wall) # number of EXPRESS attributes
+    8
+    >>> wall.GlobalId
+    '2O2Fr$t4X7Zf8NOew3FL9r'
+    >>> wall.Name = "My wall"
+    >>> wall.NonExistingAttr
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File ".\ifcopenshell.py", line 14, in __getattr__
+        except: raise AttributeError("entity instance of type '%s' has no attribute'%s'"%(self.wrapped_data.is_a(), name)) from None
+    AttributeError: entity instance of type 'IfcWallStandardCase' has no attribute 'NonExistingAttr'
+    >>> wall.GlobalId = 3
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File ".\ifcopenshell.py", line 26, in __setattr__
+        self[self.wrapped_data.get_argument_index(key)] = value
+      File ".\ifcopenshell.py", line 30, in __setitem__
+        self.wrapped_data.set_argument(idx, entity_instance.map_value(value))
+      File ".\ifc_wrapper.py", line 118, in <lambda>
+        set_argument = lambda self,x,y: self._set_argument(x) if y is None else self
+    ._set_argument(x,y)
+      File ".\ifc_wrapper.py", line 114, in _set_argument
+        def _set_argument(self, *args): return _ifc_wrapper.entity_instance__set_argument(self, *args)
+    RuntimeError: INT is not a valid type for 'GlobalId'
+    >>> f.createIfcCartesianPoint(Coordinates=(1.0,1.5,2.0))
+    #27530=IfcCartesianPoint((1.,1.5,2.))
+    >>> import uuid
+    >>> ifcopenshell.guid.compress(uuid.uuid1().hex)
+    '3x4C8Q_6qHuv$P$FYkANRX'
+    >>> new_guid = _
+    >>> owner_hist = f.by_type("IfcOwnerHistory")[0]
+    >>> new_wall = f.createIfcWallStandardCase(new_guid, owner_hist, None, None, Tag='my_tag')
+    >>> new_wall.ObjectType = ''
+    >>> new_wall.ObjectPlacement = new_wall.Representation = None
+    >>> f[92]
+    #92=IfcWallStandardCase('2O2Fr$t4X7Zf8NOew3FLIE',#1,'Basic Wall:Interior - Partition (92mm Stud):143921',$,'Basic Wall:Interior - Partition (92mm Stud):128360',#5206,#18805,'143921')
+    >>> f['2O2Fr$t4X7Zf8NOew3FLIE']
+    #92=IfcWallStandardCase('2O2Fr$t4X7Zf8NOew3FLIE',#1,'Basic Wall:Interior - Partition (92mm Stud):143921',$,'Basic Wall:Interior - Partition (92mm Stud):128360',#5206,#18805,'143921')
+    >>> f.write("out.ifc")