The documentation complaint is true of many, maybe all, AWS services: they discuss multiple generations, address multiple target audiences, and range wildly in currency and relevance, from marketing material to technical deep dives, all intermixed.

Cognito itself is a very AWS tradeoff. It's delightfully inexpensive. It quite effectively protects one of the most relentlessly attacked parts of any web service. It supports workflows essential as you scale, like SAML federation ("single sign on/SSO"). It basically works, day in and day out.

But OMG, the sharp edges! It has sharp edges to spare, even compared to other AWS services, for which sharp edges and exposed corners are just par for the course.

Then you try to go the next step, e.g. add multi-region disaster recovery and failover. That seemingly straightforward requirement to scale up is "left as an exercise for the reader."

Cognito has all the virtues of a utility service, including the developer experience.