The difference between functions that return lists and functions one that return iterators is a generic topic belonging in a FAQ or tutorial

The difference between Pool.map and Pool.imap is multiprocessing-specific. It doesn't exist in the Python 3 builtins, where map is lazy.

The tone of the new paragraph makes map() seem like it is broken

I don't read it like this. It mentions a specific situation ("very long iterables"). The wording is very prudent.

The new paragraph skirts a more essential issue. In general, mapped functions in multiprocessing should only be returning small volumes of data.

Perhaps, perhaps not. In scientific computing, many people are using multiprocessing (or concurrent.futures) with non-trivial volumes of data. It really depends on the computation time / transfer time ratio.