See also #20973.

I believe these points are already addressed in the current documentation, but it's always difficult for someone close to the implementation to document it from a newcomer's perspective. Concrete suggestions would be helpful.

How does it differ from the map type?

"It is safe for multiple goroutines to call a Map's methods concurrently."

When should it be used? When should it not be used? What are its performance characteristics.

"It is optimized for use in concurrent loops with keys that are stable over time, and either few steady-state stores, or stores localized to one goroutine per key."

"For use cases that do not share these attributes, it will likely have comparable or worse performance and worse type safety than an ordinary map paired with a read-write mutex."

I think it's odd enough it deserves a little textual example, like "accessing a mostly read-only map under high concurrency" or something along those lines." You hint at this but in an operational way rather than an illustrative one.

how to understand

For use cases that do not share these attributes, it will likely have comparable or worse performance and worse type safety than an ordinary map paired with a read-write mutex.

@yiv We don't use the issue tracker to ask questions. Please see https://golang.org/wiki/Questions. Thanks.

Change https://golang.org/cl/83796 mentions this issue: sync: document when and when not to use Map