diff --git a/src/bsdd/README.md b/src/bsdd/README.md
index 5d92dbe9d5..ae3c88fbd3 100644
--- a/src/bsdd/README.md
+++ b/src/bsdd/README.md
@@ -1,3 +1,37 @@
 # bsdd
 
 A library to interact with the buildingSMART Data Dictionary (bSDD) API.
+This packages is totally independent from other packages in IfcOpenShell and requires only a python installation to run.
+
+## Installation
+
+```bash
+pip install git+https://git@github.com/jgunstone/ifcopenshell.git@make-bsdd-installable-and-add-tests#subdirectory=src/bsdd
+# TODO ^^^ update the github domain if merged back to ifcopenshell
+
+# check your installation
+python
+>>> from bsdd import Client
+>>> client = Client()
+>>> [l["uri"] for l in client.get_dictionary()["dictionaries"] if "4.3" in l["uri"]][0]
+'https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3'
+```
+
+## Develop
+
+```bash
+# create a fork in your domain
+git clone git@github.com:<your-name>/IfcOpenShell.git
+cd src/bsdd
+
+# if you use vs code / pycharm, you can launch it from this folder
+code .
+
+# if you use conda/mamba. follow instructions below:
+# otherwise setup a dev env in your preferred way.
+mamba create -n bsdd-dev python pytest requests
+mamba activate bsdd-dev
+
+# run tests
+pytest
+```