Adds more details, especially about caveats, failure modes and pitfalls (cherry picked from commit be41c09769)
be41c09769