diff --git a/R/deprecated.R b/R/deprecated.R
index a17084b1f..a7da1c2ab 100644
--- a/R/deprecated.R
+++ b/R/deprecated.R
@@ -19,7 +19,11 @@
 #' @rdname datanames
 #' @export
 datanames <- function(x) {
-  lifecycle::deprecate_soft("0.6.1", "datanames()", details = "names()")
+  lifecycle::deprecate_soft(
+    when = "0.6.1",
+    what = "datanames()",
+    with = "names()"
+  )
   names(x)
 }
 
@@ -27,8 +31,8 @@ datanames <- function(x) {
 #' @export
 `datanames<-` <- function(x, value) {
   lifecycle::deprecate_soft(
-    "0.6.1",
-    "`datanames<-`()",
+    when = "0.6.1",
+    what = "`datanames<-`()",
     details = "invalid to use `datanames()<-` or `names()<-` on an object of class `teal_data`. See ?names.teal_data"
   )
   x
@@ -39,8 +43,8 @@ datanames <- function(x) {
 #' @keywords internal
 `names<-.teal_data` <- function(x, value) {
   lifecycle::deprecate_warn(
-    "0.6.1",
-    "`names<-.teal_data`()",
+    when = "0.6.1",
+    what = "`names<-.teal_data`()",
     details = "invalid to use `datanames()<-` or `names()<-` on an object of class `teal_data`. See ?names.teal_data"
   )
   x
diff --git a/R/teal_data-names.R b/R/teal_data-names.R
index 1c28ccd56..cf3d31b11 100644
--- a/R/teal_data-names.R
+++ b/R/teal_data-names.R
@@ -7,6 +7,8 @@
 #' To get the names of all objects, use `ls(x, all.names = TRUE)`, however, it
 #' will not group the names by the join_keys topological structure.
 #'
+#' In order to rename objects in the `teal_data` object, use base R functions (see examples).
+#'
 #' @param x A (`teal_data`) object to access or modify.
 #'
 #' @return A character vector of names.
@@ -16,9 +18,18 @@
 #' td <- within(td, mtcars <- mtcars)
 #' names(td)
 #'
+#' # hidden objects with dot-prefix
 #' td <- within(td, .CO2 <- CO2)
 #' names(td) # '.CO2' will not be returned
 #'
+#' # rename objects
+#' td <- teal_data(iris = iris)
+#' td <- within(td, {
+#'   new_iris <- iris
+#'   rm(iris)
+#' })
+#' names(td) # only 'new_iris' will be returned
+#'
 #' @export
 names.teal_data <- function(x) {
   # Sorting from `ls` can be safely done as environments don't have any order
diff --git a/man/names.teal_data.Rd b/man/names.teal_data.Rd
index 4f03fce70..9cd42c38d 100644
--- a/man/names.teal_data.Rd
+++ b/man/names.teal_data.Rd
@@ -20,13 +20,24 @@ The names are obtained from the objects listed in the \code{qenv} environment.
 Objects named with a \code{.} (dot) prefix will be ignored and not returned.
 To get the names of all objects, use \code{ls(x, all.names = TRUE)}, however, it
 will not group the names by the join_keys topological structure.
+
+In order to rename objects in the \code{teal_data} object, use base R functions (see examples).
 }
 \examples{
 td <- teal_data(iris = iris)
 td <- within(td, mtcars <- mtcars)
 names(td)
 
+# hidden objects with dot-prefix
 td <- within(td, .CO2 <- CO2)
 names(td) # '.CO2' will not be returned
 
+# rename objects
+td <- teal_data(iris = iris)
+td <- within(td, {
+  new_iris <- iris
+  rm(iris)
+})
+names(td) # only 'new_iris' will be returned
+
 }