diff --git a/docs/spec.md b/docs/spec.md
index e9e1bdf3d2..b25af610f8 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -191,6 +191,19 @@ Build requirements can also be updated in the command line: `spk install --save
 
 The install configuration specifies the environment that your package needs when it is installed or included in an spk environment.
 
+#### Environment Variables
+
+Packages can append, prepend and set environment variables at runtime if needed. It's strongly encouraged to only modify variables that your package can reasonably take ownership for. For example, the `python` package should be the only one setting `PYTHON*` variables that affect the runtime of python. This is not an enforced rule, but if you find yourself setting `PYTHONPATH`, for example, then it might mean that you are installing to a non-standard location within spfs and breaking away from the intended consistency of spfs.
+
+```yaml
+install:
+  environment:
+    - set: MYPKG_VAR
+      value: hello, world
+    - append: PATH
+      value: /spfs/opt/mypkg/bin
+```
+
 #### Requirements
 
 Packages often require other packages to be present at run-time. These requirements should be listed in the `install.requirements` section of the spec file, and follow the same semantics as build options above.