This is one of those sections that's more guide than api, so it works either way. The doc is more guide oriented so I feel like it should stay util we make the sweeping change