diff --git a/R/documentation.R b/R/documentation.R
index 633f120ee..d6dc00a95 100644
--- a/R/documentation.R
+++ b/R/documentation.R
@@ -13,6 +13,16 @@
 #'   Packages](https://r-pkgs.org)
 #' @inheritParams use_template
 #' @export
+#' @details
+#' use_package_doc() leads to an R-CMD-CHECK warning if package shares name with a
+#' function ([Github Issue](https://github.com/r-lib/usethis/issues/1170)). This can be
+#' obviated by including the following lines at the top of your mypackagename-package.R script:
+#'
+#' `@keywords internal`
+#'
+#' `@aliases reprex-package`
+#'
+#' `"_PACKAGE"`
 use_package_doc <- function(open = rlang::is_interactive()) {
   check_is_package("use_package_doc()")
   use_template(
diff --git a/man/use_package_doc.Rd b/man/use_package_doc.Rd
index 264ff4676..ff4f47fca 100644
--- a/man/use_package_doc.Rd
+++ b/man/use_package_doc.Rd
@@ -20,6 +20,17 @@ 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{
+use_package_doc() leads to an R-CMD-CHECK warning if package shares name with a
+function (\href{https://github.com/r-lib/usethis/issues/1170}{Github Issue}). This can be
+obviated by including the following lines at the top of your mypackagename-package.R script:
+
+\verb{@keywords internal}
+
+\verb{@aliases reprex-package}
+
+\code{"_PACKAGE"}
+}
 \seealso{
 The \href{https://r-pkgs.org/man.html}{documentation chapter} of \href{https://r-pkgs.org}{R Packages}
 }