diff --git a/README.md b/README.md
index c917752..7975adc 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,49 @@
-# YouTubeVideoMacro
+YouTubeVideoMacro
+=================
 
-A macro for the MoinMoin wiki for displaying embedded YouTube videos
\ No newline at end of file
+A macro for the MoinMoin wiki for displaying embedded YouTube videos.
+
+There is already a [YouTube macrco][ytm] available on the website of the
+[MoinMoin wiki][moin] software. Unfortunately the last update was in 2011.
+While it still works with the current MoinMoin version, the embedding relies
+on old [YouTube][yt] apis and still requires Flash.
+
+To simply embed single videos on an wiki page, this new plugin was written.
+Although it has not the same features as the old one, it can be used to displaying
+a single video on a wiki page.
+
+
+Installation
+------------
+
+To install the macro, copy the file `YoutubeVideo.py` into the `/path_to_wiki_instance/data/plugin/macro` directory. This method will
+propably survive a MoinMoin or Python upgrade. Make shure, that the file has
+the right ownership and permissions.
+
+
+Usage
+-----
+
+On a MoinMoin wiki page, you can embed a video by calling the macro with a
+YouTube video id:
+
+    <<Youtube(KYeMAfXrask)>>
+
+Optionally you can also provide a width and / or height parameter for the
+video:
+
+    <<Youtube(KYeMAfXrask, width=560, height=315)>>
+
+
+Remark
+------
+
+To respect user privacy (insofar this is possible with embedded content), the
+domain `https://www.youtube-nocookie.com/` is used and related videos will not
+be displayed at the end of the video.
+
+
+
+[ytm]: https://moinmo.in/MacroMarket/YouTube
+[moin]: https://moinmo.in/
+[yt]: https://www.youtube.com/