diff --git a/docs/src/docPages/overview/upgrade-guide.md b/docs/src/docPages/overview/upgrade-guide.md
index 1962276d..0ec1b9f8 100644
--- a/docs/src/docPages/overview/upgrade-guide.md
+++ b/docs/src/docPages/overview/upgrade-guide.md
@@ -1,6 +1,35 @@
 # Upgrade Guide
 
-- reasons to upgrade to tiptap 2
-- link to roadmap
+## Reasons to upgrade to tiptap 2.x
 
-## Upgrading from 1.x to 2.x
\ No newline at end of file
+* TypeScript: auto complete, less bugs, generated API documentation
+* Amazing documentation with 100+ pages
+* Active maintenance, no more updates to 1.x
+* Tons of new extensions planned
+* Less bugs, tested code based
+
+## Upgrading from 1.x to 2.x
+The new API will look pretty familiar too you, but there are a ton of changes though. To make the upgrade a little bit easier, here is everything you should do:
+
+### New document type
+**We renamed the default `Document` type from `doc` to `document`.** To keep it like that, use your own implementation of the `Document` node or migrate the stored JSON to use the new name.
+
+```js
+import Document from '@tiptap/extension-document'
+const CustomDocument = Document.name('doc').create()
+
+new Editor({
+  extensions: [
+      CustomDocument(),
+      …
+  ]
+})
+```
+
+### New extension API
+
+In case you’ve built some custom extensions for your project, you’ll need to rewrite them to fit the new API. No worries, though, you can keep a lot of your work though. The schema, commands, keys, inputRules, pasteRules all work like they did before. It’s just different how you register them.
+
+```js
+const CustomExtension = …
+```
\ No newline at end of file