diff --git a/docs/source/best-practices.md b/docs/source/best-practices.md
new file mode 100644
index 000000000..4d53b78f6
--- /dev/null
+++ b/docs/source/best-practices.md
@@ -0,0 +1,38 @@
+# Best Practices
+
+A collection of useful design tips & best practices for using traitlets in your
+application or library.
+
+## Avoid using "pure config" objects
+
+Put your traitlets config directly on the classes that are doing the work,
+rather than creating separate classes just for holding configuration. This
+keeps configuration close to the code it is configuring, and helps with
+discoverability as well.
+
+So instead of:
+
+```python
+class SpawnerConfig(LoggingConfigurable):
+    some_config = Unicode("", config=True)
+
+    some_other_config = Unicode("default", config=True)
+
+
+class Spawner:
+    def spawn(self, config: SpawnerConfig):
+        print(config.some_config)
+        # Do things with config
+```
+
+Prefer:
+
+```python
+class Spawner(LoggingConfigurable):
+    some_config = Unicode("", config=True)
+
+    some_other_config = Unicode("default", config=True)
+
+    def spawn(self):
+        print(self.some_config)
+```
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e1979dac7..88b7cfa42 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -23,6 +23,7 @@ the configuration machinery.
     trait_types
     defining_traits
     api
+    best-practices
     config
     config-api
     utils