diff --git a/R/documentation.R b/R/documentation.R
index 633f120ee..6900eb705 100644
--- a/R/documentation.R
+++ b/R/documentation.R
@@ -1,14 +1,26 @@
 #' Package-level documentation
 #'
-#' Adds a dummy `.R` file that will prompt roxygen to generate basic
+#' Adds a dummy `.R` file that will cause roxygen2 to generate basic
 #' package-level documentation. If your package is named "foo", this will make
 #' help available to the user via `?foo` or `package?foo`. Once you call
-#' `devtools::document()`, roxygen will flesh out the `.Rd` file using data from
-#' the `DESCRIPTION`. That ensures you don't need to repeat the same information
-#' in multiple places. This `.R` file is also a good place for roxygen
-#' directives that apply to the whole package (vs. a specific function), such as
-#' global namespace tags like `@importFrom`.
+#' `devtools::document()`, roxygen2 will flesh out the `.Rd` file using data
+#' from the `DESCRIPTION`. That ensures you don't need to repeat (and remember
+#' to update!) the same information in multiple places. This `.R` file is also a
+#' good place for roxygen directives that apply to the whole package (vs. a
+#' specific function), such as global namespace tags like `@importFrom`.
 #'
+#' There is one tricky case: when a **package** named "foo" also has a
+#' **function** named `foo()`. In this case, after running `use_package_doc()`,
+#' there will be an `R CMD check` warning. The solution is to set the `@aliases`
+#' for the package-level help topic by modifying the dummy `.R` file (e.g.,
+#' `foo-package.R`) as shown below (but substitute the name of your package /
+#' function for "foo"):
+#'
+#' ```
+#' #' @keywords internal
+#' #' @aliases foo-package
+#' #' "_PACKAGE"
+#' ```
 #' @seealso The [documentation chapter](https://r-pkgs.org/man.html) of [R
 #'   Packages](https://r-pkgs.org)
 #' @inheritParams use_template
diff --git a/man/use_package_doc.Rd b/man/use_package_doc.Rd
index 264ff4676..6eaa0d6a5 100644
--- a/man/use_package_doc.Rd
+++ b/man/use_package_doc.Rd
@@ -11,14 +11,27 @@ use_package_doc(open = rlang::is_interactive())
 applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
 }
 \description{
-Adds a dummy \code{.R} file that will prompt roxygen to generate basic
+Adds a dummy \code{.R} file that will cause roxygen2 to generate basic
 package-level documentation. If your package is named "foo", this will make
 help available to the user via \code{?foo} or \code{package?foo}. Once you call
-\code{devtools::document()}, roxygen will flesh out the \code{.Rd} file using data from
-the \code{DESCRIPTION}. That ensures you don't need to repeat the same information
-in multiple places. This \code{.R} file is also a good place for roxygen
-directives that apply to the whole package (vs. a specific function), such as
-global namespace tags like \verb{@importFrom}.
+\code{devtools::document()}, roxygen2 will flesh out the \code{.Rd} file using data
+from the \code{DESCRIPTION}. That ensures you don't need to repeat (and remember
+to update!) the same information in multiple places. This \code{.R} file is also a
+good place for roxygen directives that apply to the whole package (vs. a
+specific function), such as global namespace tags like \verb{@importFrom}.
+}
+\details{
+There is one tricky case: when a \strong{package} named "foo" also has a
+\strong{function} named \code{foo()}. In this case, after running \code{use_package_doc()},
+there will be an \verb{R CMD check} warning. The solution is to set the \verb{@aliases}
+for the package-level help topic by modifying the dummy \code{.R} file (e.g.,
+\code{foo-package.R}) as shown below (but substitute the name of your package /
+function for "foo"):
+
+\if{html}{\out{<div class="sourceCode">}}\preformatted{#' @keywords internal
+#' @aliases foo-package
+#' "_PACKAGE"
+}\if{html}{\out{</div>}}
 }
 \seealso{
 The \href{https://r-pkgs.org/man.html}{documentation chapter} of \href{https://r-pkgs.org}{R Packages}