diff --git a/README.md b/README.md
new file mode 100644
index 0000000000..609f80c78c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,28 @@
+# VisualEditor
+
+VisualEditor provides a visual editor for wiki pages. It is written in
+JavaScript and runs in a web browser.
+
+It uses the Parsoid parser to convert wikitext documents to annotated HTML
+which the VisualEditor is able to load, modify and emit back to Parsoid at
+which point it is converted back into wikitext.
+
+For more information about these projects, check out the [VisualEditor][]
+and [Parsoid][] pages on mediawiki.
+
+
+## Developing and installing
+
+For information on installing VisualEditor on a local wiki, please
+see https://www.mediawiki.org/wiki/Extension:VisualEditor
+
+For information about contributing code to VisualEditor, see
+[CODING.md][].  Patch submissions are reviewed and managed with
+[Gerrit][].  There is also [API documentation][] available for the
+VisualEditor.
+
+[VisualEditor]:      http://www.mediawiki.org/wiki/VisualEditor
+[Parsoid]:           http://www.mediawiki.org/wiki/Parsoid
+[CODING.md]:         CODING.md
+[API documentation]: https://doc.wikimedia.org/VisualEditor/master/
+[Gerrit]:            https://www.mediawiki.org/wiki/Gerrit
diff --git a/README.txt b/README.txt
deleted file mode 100644
index cc54c24368..0000000000
--- a/README.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-VisualEditor provides a visual editor for wiki pages. It is written in
-JavaScript and runs in a web browser.
-
-It uses the Parsoid parser to convert wikitext documents to annotated HTML
-which the VisualEditor is able to load, modify and emit back to Parsoid at
-which point it is converted back into wikitext.
-
-For more information about these projects, check out the wiki:
-
-	* http://www.mediawiki.org/wiki/VisualEditor
-	* http://www.mediawiki.org/wiki/Parsoid