Hi Ralf,
Overall, this looks good. But I think the subclassing section is somewhat misleading in suggesting `ndarray` is not well designed to be subclassed. At least, for neither my work on Quantity nor that on MaskedArray, I've found that the design of `ndarray` itself was a problem. Instead, it was the functions that were, as most were not written with subclassing or duck typing in mind, but rather with the assumption that all input should be an array, and that somehow it is useful to pass anything users pass in through `asarray`. With then layers on top to avoid this in specific circumstances... But perhaps this is what you meant? (I would agree, though, that some ndarray subclasses have been designed poorly - especially, matrix, which then led to a problematic duck array in sparse - and that this has resulted in substantial hassle. Also, subclassing the subclasses is much more problematic that subclassing ndarray - MaskedArray being a particularly annoying example!)
The subclassing section also notes that subclassing has been discouraged for a long time. Is that so? Over time, I've certainly had comments from Nathaniel and some others in discussions of PRs that go in that direction, which perhaps reflected some internal consensus I wasn't aware of, but the documentation does not seem to discourage it (check, e.g., the subclassing section [1]). I also think that it may be good to keep in mind that until `__array_ufunc__`, there wasn't much of a choice - support for duck arrays was even more half-hearted (hopefully to become much better with `__array_function__`).
Overall, it seems to me that these days in the python eco-system subclassing is simply expected to work. Even within numpy there are other examples (e.g., ufuncs, dtypes) for which there has been quite a bit of discussion about the benefits subclasses would bring.