Following on from MONGOID-5582, the solution in that ticket failed to account for the edge case where shard keys have "." characters in the name. (See https://www.mongodb.com/docs/manual/core/dot-dollar-considerations)

I believe it should be possible to fix the recursion in the shard key parsing so that it will only recurse if the current segment matches the name of an embedded document.

Update documentation to better explain this scenario and provide best practices