diff --git a/pw_protobuf/docs.rst b/pw_protobuf/docs.rst
index ca71c12..7b2cc69 100644
--- a/pw_protobuf/docs.rst
+++ b/pw_protobuf/docs.rst
@@ -495,6 +495,29 @@
     return status.IsOutOfRange() ? OkStatus() : status;
   }
 
+
+Handling of packages
+====================
+
+Package declarations in ``.proto`` files are converted to namespace
+declarations. Unlike ``protoc``'s native C++ codegen, pw_protobuf appends an
+additional ``::pwpb`` namespace after the user-specified package name: for
+example, ``package my.cool.project`` becomes ``namespace
+my::cool::project::pwpb``. We emit a different package name than stated, in
+order to avoid clashes for projects that link against multiple C++ proto
+libraries in the same library.
+
+..
+  TODO(b/258832150) Remove this section, if possible
+
+In some cases, pw_protobuf codegen may encounter external message references
+during parsing, where it is unable to resolve the package name of the message.
+In these situations, the codegen is instead forced to emit the package name as
+``pw::pwpb_xxx::my::cool::project``, where "pwpb_xxx" is the name of some
+unspecified private namespace. Users are expected to manually identify the
+intended namespace name of that symbol, as described above, and must not rely
+on any such private namespaces, even if they appear in codegen output.
+
 -------
 Codegen
 -------
diff --git a/pw_protobuf/py/pw_protobuf/proto_tree.py b/pw_protobuf/py/pw_protobuf/proto_tree.py
index 2f807f5..d83c607 100644
--- a/pw_protobuf/py/pw_protobuf/proto_tree.py
+++ b/pw_protobuf/py/pw_protobuf/proto_tree.py
@@ -42,11 +42,11 @@
 # codegen. This namespace provides us with an alternative, more verbose
 # namespace that the codegen can use as a fallback in these cases. For example,
 # for the symbol name `my.external.package.ProtoMsg.SubMsg`, we would use
-# `::pw::pwpb_codegen_detail::my::external::package:ProtoMsg::SubMsg` to refer
+# `::pw::pwpb_codegen_private::my::external::package:ProtoMsg::SubMsg` to refer
 # to the pw_protobuf generated code, when package name info is not available.
 #
 # TODO(b/258832150) Explore removing this if possible
-EXTERNAL_SYMBOL_WORKAROUND_NAMESPACE = 'pw::pwpb_codegen_detail'
+EXTERNAL_SYMBOL_WORKAROUND_NAMESPACE = 'pw::pwpb_codegen_private'
 
 
 class ProtoNode(abc.ABC):