The documentation for v10 needs some work. v10 isn't a small API change, it completely changes the way a user has to interact with the library. I have used emotion on all of my projects for over a year so it's not like I'm a newb to this library. If it's hard for me to understand just what is going on I can't imagine the hurdle for actual newcomers.

Given the obscure API that comes with this version (@emotion/core vs emotion, jsx as an used import?This pragma is supposed to be more clear/easy to use than a babel plugin? ), it would be nice if each of these new packages had their own documentation, since apparently they're all completely different. As it stands you have them all randomly strewn about with notes like 'you only need this if...'

Grant you I'm coming at this from a place of general negativity because I've disagreed with this direction from the start (gave a thumbs down on your initial proposal for example), but those feelings are compounded by the fact that the migration guide isn't at all clear. It makes suggestions about moving from emotion to @emotion/core but still says elsewhere in the docs you can still use emotion. OK. Well, when should I use each? Why should I use @emotion/core over emotion? What am I missing out on by not doing so?

I really hope this issue with the docs gets ironed out. I'd help, but clearly I don't understand the API as it is so I don't have anything to offer. The only concrete suggestions I have are that you create completely separate sites for emotion and @emotion/core and highlight whatever the differences are somewhere in addition to explaining more clearly what jsx is for. Some more clarity about the new css prop usage would also be nice.