diff --git a/src/ifcopenshell-python/ifcopenshell/express/README.md b/src/ifcopenshell-python/ifcopenshell/express/README.md
new file mode 100644
index 0000000000..6def60b872
--- /dev/null
+++ b/src/ifcopenshell-python/ifcopenshell/express/README.md
@@ -0,0 +1,27 @@
+# IfcOpenShell express schema parser and code generator
+
+This folder contains Python code to generate C++ type information based on an
+Express schema. In particular is has only been tested using recent version of
+the IFC schema and will most likely fail on any other Express schema.
+
+The code can be invoked in the following way and results in several code outputs
+named according to the schema name in the Express file. A python 3 interpreter
+with the `pyparsing` (`pip install pyparsing`) library is required.
+
+## Command line usage for code generation
+
+~~~
+# python3 bootstrap.py express.bnf > express_parser.py
+python3 express_parser.py IFC2X3_TC1.exp header implementation schema_class definitions
+~~~
+
+## Programmatic usage
+
+~~~py
+import ifcopenshell
+import ifcopenshell.express
+schema = ifcopenshell.express.parse('IFC.exp')
+ifcopenshell.register_schema(schema)
+f = ifcopenshell.file(schema=schema.schema.name())
+f.createIfcProject(ifcopenshell.guid.new())
+~~~
diff --git a/src/ifcopenshell-python/ifcopenshell/express/README.txt b/src/ifcopenshell-python/ifcopenshell/express/README.txt
deleted file mode 100644
index 793b4c9c67..0000000000
--- a/src/ifcopenshell-python/ifcopenshell/express/README.txt
+++ /dev/null
@@ -1,12 +0,0 @@
-This folder contains Python code to generate C++ type information based on an
-Express schema. In particular is has only been tested using recent version of
-the IFC schema and will most likely fail on any other Express schema.
-
-The code can be invoked in the following way and results in several code outputs
-named according to the schema name in the Express file. A python 3 interpreter
-with the pyparsing [1] library is required.
-
-$ python bootstrap.py express.bnf > express_parser.py
-$ python express_parser.py IFC2X3_TC1.exp header implementation schema_class definitions
-
-[1] http://pyparsing.wikispaces.com/Download+and+Installation