This is an epic, because it needs to be broken down into smaller stories - I've attempted to make that breakdown here.

Currently, the traffic management section of the Service Mesh docs is organized by components - VirtualServices, Hosts, Destination Rules, Gateways, etc. The problem with this is that one has to read the entire documentation (as well as a lot of istio.io) before they're able to implement a service mesh use case. Meanwhile, these components are well documented at istio.io, thus we don't need to repeat that here. Instead, we should look to focus on Service Mesh use cases in the context of OpenShift.

This section should be divided into internal mesh and external / edge traffic, as they are different use cases, and may even be different users.

External / Edge Traffic 

This should be a new section of the doc - separate from "Traffic Management", targeting an admin/ops user. The best source on this topic at a high-level within OpenShift, is this blog post: https://www.openshift.com/blog/design-considerations-at-the-edge-of-the-servicemesh. We'll then need to discuss Ingress and Egress Gateways, When to use an OpenShift Route, when not to, automatic route creation (IOR), TLS termination. This section could also highlight 3Scale as an API Management solution. Basically, the implementation side of the blog post. Some of this is already in the "Traffic Management" section.

Internal Mesh Traffic Management

This should be separate section, focused on a developer persona. It could also highlight Kiali as a means of driving the use caes.

Those use cases include:

• Making Services Resilient - This should likely be its own section. It would cover creating timeouts, retries and circuit breakers. It could also cover "Chaos engineering" for validating that your services - introducing random pauses, delays, etc. to validate resilience. This could be done via Kiali.
• Releasing Services with Traffic Shaping - A section on rolling out new versions of applications using canary deployments (a small amount of traffic is sent to a new version of a service), mirrored deployments (production traffic is sent to both an existing and new service), A/B testing (traffic is sent to different versions based on some criteria - header value or randomness).

 The above use cases are well documented in training material, such as DO328. The reference manual for that course could be used as guidance for this documentation. I have attached the guide for that course to this issue.