diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e3ceebd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+## Conversion utilities
+
+This repository is currently intended for common conversions needed by CJVT developers. For the
+moment, this is limited to JOS msds and properties.
+
+### JOS msds and properties
+
+You can use the Msd and Properties to encode, and convert between the two types in either direction
+(specifying both the input and output language (English or Slovene)) or just translate between
+English and Slovene. Example usage:
+
+```
+>>> from conversion_utils.jos_msds_and_properties import Converter, Msd, Properties
+>>> converter = Converter()
+>>> msd = Msd('Sozem', 'sl')
+>>> msd.code
+'Sozem'
+>>> msd.language
+'sl'
+>>> properties = converter.msd_to_properties(msd, 'en')
+>>> properties.category
+'noun'
+>>> properties.lexeme_feature_map
+{'type': 'common', 'gender': 'feminine'}
+>>> properties.form_feature_map
+{'number': 'singular', 'case': 'locative'}
+>>> properties.language
+'en'
+>>> msd2 = converter.properties_to_msd(properties, 'sl')
+>>> msd2 == msd
+True
+>>> print(converter.translate_msd(msd, 'en'))
+code=Ncfsl, language=en
+>>> print(converter.translate_properties(properties, 'sl'))
+language=sl, category=samostalnik, lexeme features={'vrsta': 'občno_ime', 'spol': 'ženski'}, form_features={'število': 'ednina', 'sklon': 'mestnik'}
+```
\ No newline at end of file