That's how typical Apple "magical/just works" features are implemented, i.e. very ugly behind the curtain. Documenting means revealing the edge cases and the l

That's how typical Apple "magical/just works" features are implemented, i.e. very ugly behind the curtain. Documenting means revealing the edge cases and the limitations, which engineering knows is the best kind of documentation. But marketing people are invested in the "magic". Marketing people have too much sway at Apple.