diff --git a/NEWS.md b/NEWS.md
index 5b3ec85c..0d420633 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -13,6 +13,9 @@
   that aren't two characters, and add an explanation of this in the
   help info. (Issue #220)
 
+- More fully explain the use of weights in `est_herit()` and
+  `scan1()`. (Issue #221)
+
 
 ## qtl2 0.32 (2023-04-21)
 
diff --git a/R/est_herit.R b/R/est_herit.R
index 1a507601..5b262a4f 100644
--- a/R/est_herit.R
+++ b/R/est_herit.R
@@ -26,6 +26,10 @@
 #' matrix \eqn{\sigma^2 [h^2 (2 K) + I]}{sigmasq*[hsq*2*K+I]} where
 #' \eqn{K} is the kinship matrix and \eqn{I} is the identity matrix.
 #'
+#' If `weights` are provided, the covariance matrix becomes
+#' \eqn{\sigma^2 [h^2 (2 K) + D]}{sigmasq*[hsq*2*K+D]} where
+#' \eqn{D} is a diagonal matrix with the reciprocal of the weights.
+#'
 #' For each of the inputs, the row names are used as
 #' individual identifiers, to align individuals.
 #'
diff --git a/R/scan1.R b/R/scan1.R
index 52cf761f..2566bfbc 100644
--- a/R/scan1.R
+++ b/R/scan1.R
@@ -61,6 +61,10 @@
 #' mean 0 and covariance matrix \eqn{\sigma^2 [h^2 (2 K) +
 #' I]}{sigmasq*[hsq*2*K+I]}, taking \eqn{h^2}{hsq} to be known.
 #'
+#' Note that if `weights` are provided, the covariance matrix becomes
+#' \eqn{\sigma^2 [h^2 (2 K) + D]}{sigmasq*[hsq*2*K+D]} where
+#' \eqn{D} is a diagonal matrix with the reciprocal of the weights.
+#'
 #' For each of the inputs, the row names are used as
 #' individual identifiers, to align individuals. The `genoprobs`
 #' object should have a component `"is_x_chr"` that indicates
diff --git a/man/est_herit.Rd b/man/est_herit.Rd
index d4b39622..5450ce38 100644
--- a/man/est_herit.Rd
+++ b/man/est_herit.Rd
@@ -49,6 +49,10 @@ We fit the model \eqn{y = X \beta + \epsilon}{y = Xb + e} where
 matrix \eqn{\sigma^2 [h^2 (2 K) + I]}{sigmasq*[hsq*2*K+I]} where
 \eqn{K} is the kinship matrix and \eqn{I} is the identity matrix.
 
+If \code{weights} are provided, the covariance matrix becomes
+\eqn{\sigma^2 [h^2 (2 K) + D]}{sigmasq*[hsq*2*K+D]} where
+\eqn{D} is a diagonal matrix with the reciprocal of the weights.
+
 For each of the inputs, the row names are used as
 individual identifiers, to align individuals.
 
diff --git a/man/scan1.Rd b/man/scan1.Rd
index ffdfc716..a32494b5 100644
--- a/man/scan1.Rd
+++ b/man/scan1.Rd
@@ -96,6 +96,10 @@ matrix of covariates \eqn{\epsilon}{e} is multivariate normal with
 mean 0 and covariance matrix \eqn{\sigma^2 [h^2 (2 K) +
 I]}{sigmasq*[hsq*2*K+I]}, taking \eqn{h^2}{hsq} to be known.
 
+Note that if \code{weights} are provided, the covariance matrix becomes
+\eqn{\sigma^2 [h^2 (2 K) + D]}{sigmasq*[hsq*2*K+D]} where
+\eqn{D} is a diagonal matrix with the reciprocal of the weights.
+
 For each of the inputs, the row names are used as
 individual identifiers, to align individuals. The \code{genoprobs}
 object should have a component \code{"is_x_chr"} that indicates