Flakes aren’t documented well because they aren’t stable. The actions of Detsys to push flakes as stable are hurting the feature in the long run. It shouldn’t be a problem to break an experimental feature. Now many people and organizations are depending on Flakes, and flaws they have are much harder to fix.