diff --git a/README.md b/README.md
index d5c577d38475f3f63d44c8fef62fd54b636c4591..84e8393fcbfb641bf7818b91a14921f8781c24ce 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,88 @@
 # de.hftstuttgart.cityunits
 
-Create Eclipse P2 repository with Ecore data types for units based on Indriya reference implementation and some special units for urban simulation.
+Create Eclipse P2 repository with Ecore data types `QuantityDouble` and `QuantityLong` for units based on Indriya reference implementation of Units of Measurement Java specification (JSR 385) and some special units for urban simulation.
 
-To add OSGi bundles published in this P2 repository add site [https://transfer.hft-stuttgart.de/pages/neqmodplus/de.hft-stuttgart.cityunits/release_target_100/]() to a running Eclipse instance via `Eclipse -> Preferences -> Install/Update -> Available Software Sites -> Add...` or to a target platform definition via `Eclipse -> Preferences -> Plug-in Development -> Target Platform -> Edit...`.
+To add OSGi bundles published in this P2 repository add site [https://transfer.hft-stuttgart.de/pages/neqmodplus/de.hft-stuttgart.cityunits/release_target_102/]() to a running Eclipse instance via `Eclipse -> Preferences -> Install/Update -> Available Software Sites -> Add...` or to a target platform definition via `Eclipse -> Preferences -> Plug-in Development -> Target Platform -> Edit...`.
+
+
+For an introduction on dealing with units in Java, see
+[Baeldung: Introduction to javax.measure](https://www.baeldung.com/javax-measure).
+
+Find demos on how to define new dimensions and units, e.g. in the energy domain under [github.com/unitsofmeasurement](https://github.com/unitsofmeasurement/uom-demos/tree/master/domain).
+
+Some examples for valid units:
+
+| Symbol   | Dimension           
+| -------- | ------------------- 
+| Hz       | 1/[T] 
+| Bq       | 1/[T] 
+| A        | [I] 
+| F        | [I]²·[T]^4/([L]²·[M]) 
+| S        | [I]²·[T]³/([L]²·[M]) 
+| C        | [I]·[T] 
+| cd       | [J] 
+| lm       | [J] 
+| lx       | [J]/[L]² 
+| m        | [L] 
+| m/s      | [L]/[T] 
+| km/h     | [L]/[T] 
+| m/s²     | [L]/[T]² 
+| m²       | [L]² 
+| Sv       | [L]²/[T]² 
+| Gy       | [L]²/[T]² 
+| H        | [L]²·[M]/([I]²·[T]²) 
+| Ω        | [L]²·[M]/([I]²·[T]³) 
+| Wb       | [L]²·[M]/([I]·[T]²) 
+| V        | [L]²·[M]/([I]·[T]³) 
+| J        | [L]²·[M]/[T]² 
+| W        | [L]²·[M]/[T]³ 
+| l        | [L]³ 
+| m³       | [L]³ 
+| N        | [L]·[M]/[T]² 
+| kg       | [M] 
+| g        | [M] 
+| T        | [M]/([I]·[T]²) 
+| Pa       | [M]/([L]·[T]²) 
+| mol      | [N] 
+| kat      | [N]/[T] 
+| h        | [T] 
+| year     | [T] 
+| s        | [T] 
+| day      | [T] 
+| week     | [T] 
+| min      | [T] 
+| K        | [Θ] 
+| ℃        | [Θ] 
+| one      | one 
+| %        | one 
+| rad      | one 
+| sr       | one 
+
+Some derived units of special interest for urban simulation like kW·h (encodes kWh) as measure of energy or m³/min as measure of flow rate.
+
+| Symbol   | Dimension           
+| -------- | -------------- 
+| W·s      | [L]²·[M]/[T]² 
+| W·h      | [L]²·[M]/[T]² 
+| kW·h     | [L]²·[M]/[T]² 
+| MW·h     | [L]²·[M]/[T]² 
+| m³/min   | [L]³/[T] 
+| m³/h     | [L]³/[T] 
+| m³/s     | [L]³/[T] 
+| m³/d     | [L]³/[T] 
+| l/min    | [L]³/[T] 
+
+Some units of special interest for urban simulation introduced with this plug-in:
+
+| Symbol   | Dimension           
+| -------- | -------------- 
+| W/m²     | [M]/[T]³ Intensity
+| ppm      | one 
+| dB       | one 
+| g COâ‚‚eq  | [M] CarbonEmission
+| kg COâ‚‚eq | [M] CarbonEmission
+| t COâ‚‚eq  | [M] CarbonEmission
+| €        | [$]
+| $        | [$]
+
+Note that monetary units have been added ad hoc to City Units to model costs, but may be abandoned in future.