Make the link to Understanding JSON Schema more prominent.

(And remove some ancient language from when it was a twinkle in
someone's eye).

2 files changed, 7 insertions, 5 deletions

diff --git a/docs/conf.py b/docs/conf.py
index b821453..af57de0 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -89,6 +89,7 @@ from jsonschema import *
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "ujs": ("https://json-schema.org/understanding-json-schema/", None),
 }
 
 
diff --git a/docs/validate.rst b/docs/validate.rst
index 50580bd..d59d634 100644
--- a/docs/validate.rst
+++ b/docs/validate.rst
@@ -5,6 +5,12 @@ Schema Validation
 
 .. currentmodule:: jsonschema
 
+.. tip::
+
+   Most of the documentation for this package assumes you're familiar with the fundamentals of writing JSON schemas themselves, and focuses on how this library helps you validate with them in Python.
+
+   If you aren't already comfortable with writing schemas and need an introduction which teaches about JSON Schema the specification, you may find `Understanding JSON Schema <ujs:basics>` to be a good read!
+
 
 The Basics
 ----------
@@ -15,11 +21,6 @@ The simplest way to validate an instance under a given schema is to use the
 .. autofunction:: validate
     :noindex:
 
-.. [#] For information on creating JSON schemas to validate
-    your data, there is a good introduction to JSON Schema
-    fundamentals underway at `Understanding JSON Schema
-    <https://json-schema.org/understanding-json-schema/>`_
-
 .. _validator-protocol:
 
 The Validator Protocol