diff --git a/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt b/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt
index 2564834e1ede..a5d4583afd82 100644
--- a/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt
+++ b/Documentation/doc/Documentation/Developer_manual/Chapter_namespaces.txt
@@ -13,19 +13,31 @@ but the better alternative is the usage of `namespace`.
 
 \section Developer_manualNamespaceCGAL Namespace CGAL
 
-All names introduced by \cgal should be in namespace `CGAL`, <I>e.g.</I>:
+All names introduced by \cgal should be in namespace `CGAL`,  or in a subnamespace
+corresponding to a package, <I>e.g.</I>:
 \code{.cpp}
 #include <something>
 
 namespace CGAL {
 
-class My_new_cgal_class {};
+/*!
+  * This class ...
+  */
+class Foo {};
+
+
+namespace Polygon_mesh_processing {
 
-My_new_cgal_class
-my_new_function( My_new_cgal_class& );
+/*!
+  * modifies `f` by ...
+  */
+void
+bar( foo & f);
 
+} // namespace Polygon_mesh_processing
 } // namespace CGAL
 \endcode
+
 Make sure not to have include statements inside the
 `namespace CGAL`. Otherwise, all names defined in the file included will be
 added to the namespace.
@@ -35,19 +47,15 @@ added to the namespace.
 All names introduced by \cgal which are not documented to the user
 should be under an `internal` subnamespace of `CGAL`, <I>e.g.</I>:
 \code{.cpp}
-namespace CGAL { namespace internal {
-
-class My_undocumented_class {};
-
-void my_new_function( My_undocumented_class& );
-
-}} // namespace CGAL::internal
-
-namespace CGAL { namespace internal { namespace Package { namespace tags {
+namespace CGAL {
+namespace Polygon_mesh_processing {
+namespace internal {
 
-class Some_further_class_local_to_Package;
+class Baz_used_by_foo {};
 
-}}}} // namespace CGAL::internal::Package::tags
+} // namespace internal
+} // namespace Polygon_mesh_processing
+} // namespace CGAL
 \endcode
 
 \section Developer_manualNoteonglobaltemplatefunctions Note on global template functions