Agreed the documentation could be a lot better. I wonder about a visual approach to using DataFrames and Series with all the different methods to demonstrated more clearly what's being done.
http://nikgrozev.com/2015/07/01/reshaping-in-pandas-pivot-pi...
(I´m not affiliated to site)