diff --git a/CITATION.cff b/CITATION.cff
index 4bdf4d04e..398f253d8 100644
--- a/CITATION.cff
+++ b/CITATION.cff
@@ -1,6 +1,21 @@
+# Citation information for this repository.                         -*- yaml -*-
+#
+# CITATION.cff files provide human- & machine-readable citation information for
+# software and datasets. GitHub, Zenodo, and the Zotero browser plugin all use
+# CFF files automatically if provided. https://citation-file-format.github.io/.
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 cff-version: 1.2.0
 message: If you use Stim, please cite it using this metadata.
 
+# CITATION.cff files describe how to cite software or datasets, with the goal of
+# making software and data be citable in their own right. However, sometimes
+# projects want citations to go to a paper instead. 'Preferred-citation' serves
+# to communicate that. The distinction matters in different situations. If this
+# field is present, GitHub uses the value for the "cite this repository" button
+# and ignores the rest of this file; conversely, the Zenodo-GitHub integration
+# ignores this field when creating an entry for a new software release because
+# the Zenodo entry is specifically about the software in this repository.
 preferred-citation:
   type: article
   authors:
@@ -19,6 +34,8 @@ preferred-citation:
       Verein zur Förderung des Open Access Publizierens in den
       Quantenwissenschaften
 
+# The remaining metadata in this file describes the current software release.
+
 title: Stim
 abstract: >-
   Stim is a tool for high performance simulation and analysis of quantum
@@ -34,11 +51,14 @@ license: Apache-2.0
 type: software
 identifiers:
   - description: The GitHub repository for Stim
-    value: https://quantumai.google/Stim
+    value: https://github.com/quantumlib/Stim
     type: url
   - description: PyPI project for Stim
     value: https://pypi.org/project/Stim
     type: url
+  - description: Publication about Stim
+    value: 10.22331/q-2021-07-06-497
+    type: doi
 keywords:
   - algorithms
   - API