Restore old intro, add note at top.

1 files changed, 18 insertions, 4 deletions

diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst
index 5d89f2e78..addc403b8 100644
--- a/doc/source/reference/arrays.classes.rst
+++ b/doc/source/reference/arrays.classes.rst
@@ -6,10 +6,24 @@ Standard array subclasses
 
 .. currentmodule:: numpy
 
-Subclassing a ``numpy.ndarray`` is possible but if your goal is to create an
-array with *modified* behavior, as do dask arrays for distributed computation
-and cupy arrays for GPU-based computation, subclassing is discouraged. Instead,
-using numpy's :ref:`dispatch mechanism <basics.dispatch>`_ is recommended.
+.. note::
+
+    Subclassing a ``numpy.ndarray`` is possible but if your goal is to create
+    an array with *modified* behavior, as do dask arrays for distributed
+    computation and cupy arrays for GPU-based computation, subclassing is
+    discouraged. Instead, using numpy's
+    :ref:`dispatch mechanism <basics.dispatch>` is recommended.
+
+The :class:`ndarray` can be inherited from (in Python or in C)
+if desired. Therefore, it can form a foundation for many useful
+classes. Often whether to sub-class the array object or to simply use
+the core array component as an internal part of a new class is a
+difficult decision, and can be simply a matter of choice. NumPy has
+several tools for simplifying how your new object interacts with other
+array objects, and so the choice may not be significant in the
+end. One way to simplify the question is by asking yourself if the
+object you are interested in can be replaced as a single array or does
+it really require two or more arrays at its core.
 
 Note that :func:`asarray` always returns the base-class ndarray. If
 you are confident that your use of the array object can handle any