diff --git a/README.contributing b/README.contributing
index 5e5caa7e2..04242b099 100644
--- a/README.contributing
+++ b/README.contributing
@@ -20,25 +20,30 @@ Python code, please reach out on the support site before you begin work, as
 some changes may be more appropriately done in an add-on instead.
 
 Please hold off on large refactoring projects for now, as it risks introducing
-bugs and breaking add-ons that depend on certain type signatures. If you're
-working on an isolated part of the codebase covered by unit tests, then such
-changes may be accepted, but larger changes are less likely to be at this
-time.
+bugs, and many addons currently rely on certain variable/method names and
+type signatures. If you're working on an isolated part of the codebase
+covered by unit tests, then such changes may be accepted, but larger changes
+are less likely to be at this time.
 
 Type hints
 -----------
 
 Type hints have recently been added to parts of the codebase, mainly using
-automated tools. Patches that improve the type hints are welcome, but
-pragmatism is advised. Anki's codebase is old and of varying quality, and
-there are parts that are difficult to type properly. Don't feel the need to
-avoid 'Any' when a proper type is impractical.
-
-Please use type hints in any new code that you are contributing.
+automated tools. At the moment, large parts of the codebase are still missing
+type hints, and some of the hints that do exist are incorrect or too general.
 
 When running 'make check', Anki uses mypy to typecheck the code. Mypy only
-checks parts of the code that have type signatures, so adding more type
-signatures to the code improves code coverage.
+checks functions that have type signatures, so adding more type signatures to
+the code increases the amount of code that mypy is able to analyze.
+
+Patches that improve the type hints would be appreciated. And if you're
+adding new functionality, please use type hints in the new code you write
+where practical.
+
+Parts of Anki's codebase use ad-hoc data structures like nested dictionaries
+and lists, and they can be difficult to fully type. Don't worry too much about
+getting the types perfect - even a partial type like Dict[str, Any] or
+List[Tuple] is an improvement over no types at all.
 
 Anki bundles Qt stubs, but they are not perfect, so you'll find when doing
 things like connecting signals, you may have to add the following to the end
@@ -51,6 +56,29 @@ import the types from each module into the other one, as it can cause a cyclic
 import. An example of how to work around this can be seen at
 https://github.com/dae/anki/commit/ed0b3d337458d7161811547932b6476f2d4bc887
 
+Hooks
+-------
+
+If you're writing an add-on and would like to extend a function that doesn't
+currently have a hook, a pull request that adds the required hooks would be
+welcome. If you could mention your use case in the pull request, that would be
+appreciated.
+
+The GUI hooks try to follow a consistent naming format:
+
+([module]) [subject] [passive verb]
+
+For example, editor_context_menu_will_show, browser_row_did_change, etc. This
+makes it easier to locate relevant hooks in autocomplete by typing a prefix.
+Using "did" instead of the past test "changed" can seem awkward, but makes it
+consistent with "will", and is similar to the naming style used in iOS's
+libraries.
+
+The hook code is automatically generated using the definitions in
+pylib/tools/genhooks.py and qt/tools/genhooks_gui.py. Adding a new definition
+in one of those files and running 'make develop' will update pylib/anki/hooks
+.py or qt/aqt/gui_hooks.py.
+
 Tests Must Pass
 ----------------