diff --git a/jedi/third_party/README_typeshed.md b/jedi/third_party/README_typeshed.md
new file mode 100644
index 00000000..516b030e
--- /dev/null
+++ b/jedi/third_party/README_typeshed.md
@@ -0,0 +1,14 @@
+# Typeshed in Jedi
+
+Typeshed is used in Jedi to provide completions for all the stdlib modules.
+
+The relevant files in jedi are in `jedi/inference/gradual`. `gradual` stands
+for "gradual typing".
+
+## Updating Typeshed
+
+Currently Jedi has a custom implementation hosted in
+https://github.com/davidhalter/typeshed.git for two reasons:
+
+- Jedi doesn't understand Tuple.__init__ properly.
+- Typeshed has a bug: https://github.com/python/typeshed/issues/2999