doc: Corrections and improvements to panel user guide.

Author: alanconway

doc/README.adoc

@@ -4,20 +4,20 @@
 
 The troubleshooting panel displays a graph of related resources and observability signals.
 Clicking on a node in the graph opens a console page showing the details of each resource or signal.
-Nodes in the graph represent a resource or signal type, edges represent relationships.
+Nodes in the graph represent a type of resource or signal, while edges represent relationships.
 
 The panel provides a map of related information, so you can navigate more quickly to relevant data.
 It may also help to find related information that you were not aware of.
 
-Lets consider the example of troubleshooting an Alert on the OCP console.
+Consider an example of troubleshooting an Alert on the OCP console.
 
 == Opening the panel
 
 First open the alert of interest in the console.
-Now open the troubleshooting panel [FIXME global button]
+Now open the troubleshooting panel [FIXME screenshot of global button ]
 
-Opening panel shows a _neighbourhood_ of the resource currently displayed in the console.
-A neighbourhood graph starts at the current resource, and includes related objects up to
+Opening the panel shows a _neighbourhood_ of the resource currently displayed in the console.
+A neighbourhood is a graph that starts at the current resource, and includes related objects up to
 3 steps away from the starting point.
 
 NOTE: Not all resource types are currently supported, more will be added in future.
@@ -27,41 +27,49 @@ For an unsupported resource, the panel will be empty.
 image::images/panel-graph.png[]
 
 
-<1> Alert(1) node represents the starting point alert in the console. TYPE OF ALERT
-<2> Pod(1) indicates that there is a single Pod resource associated with this alert. Clicking on this node will open a console search showing the related pod directly.
-<3> Event(2) there are two kuberenetes events associated with the Pod, you can see them by clicking this node.
-<3> Logs(74) The pod has emitted logs, click to jump to them.
-<4> Metrics(105) There are many metrics associated with every Pod.
-<6> Network(6) shows that there are network events, which means the pod has communicated over the network. The remaining nodes are the Service, Deployment and DaemonSet that the pod has communicated with.
-<7> Focus: Clicking on nodes in the graph will change what is shown in the main console page, but the graph will not change.
-    You can also navigate using links on the console page while the panel is open.
-    To update the graph, click "Focus". This will draw a new graph using the resource shown in the main page as the starting point.
-<8> Show Query enables some experimental features, see below.
-
-NOTE: Clicking on a node may sometimes show fewer results than are indicated on the graph. This is a known issue that will be addressed in future.
+<1> Alert(1): This node represents the starting point, a `KubeContainerWaiting` alert that was displayed in the console.
+<2> Pod(1): This node indicates there is a single Pod resource associated with this alert. Clicking on this node will show the pod details in the console.
+<3> Event(2): There are two kuberenetes events associated with the Pod, and you can see them by clicking this node.
+<3> Logs(74): The pod has emitted 74 lines of logs. Click to show them.
+<4> Metrics(105): There are always many metrics associated with every Pod.
+<6> Network(6): There are network events associated with the pod, which means it has communicated with other resources in the cluster.
+    The remaining Service, Deployment and DaemonSet nodes are the resources that the pod has communicated with.
+<7> Focus: Clicking nodes changes what is shown in the main console. You can navigate using links on the console page while the panel is open.
+    The graph will not change until you click "Focus".
+    This will draw a new graph starting from the resource shown in the main console.
+<8> Show Query: enables experimental features detailed below.
 
+NOTE: Clicking on a node may sometimes show fewer results than are indicated on the graph.
+This is a known issue that will be addressed in future.
 
 == Experimental features
 
 [.border]
 image::images/query-details.png[]
 
 <1> Hide Query hides the experimental features.
-<2> The "Korrel8r query" that identifies the starting point for the graph. This query language is experimental and will change in future.
-    It is updated by the "Focus" button to correspond to the resources in the main console window. (TODO upstream reference or no?)
+<2> The query that identifies the starting point for the graph. The format of this query is experimental and may change in future.
+    footnote:[This query language is part of https://korrel8r.github.io/korrel8r[Korrel8r], the correlation engine used to create the graphs]
+    The "Focus" button updates the query to match the resources in the main console window.
 <3> Neighbourhood depth: increase or decrease to see a smaller or larger neighbourhood.
     Note: setting a large value in a large cluster may cause the query to fail if the number of results is too big.
 <4> Goal class: Selecting this option will do a _goal directed search_ instead of a neighbourhood search.
     A goal directed search will show all paths from the starting point to the goal _class_ , which indicates a type of resource or signal.
-    The format of the goal class is experimental and may change. Currently valid goals are
-    - `k8s:RESOURCE[VERSION.[GROUP]]` - identifies a Kind of kuberenetes resource. For example `k8s:Pod` or `k8s:Deployment.apps.v1`.
-    - `alert:alert` - any alert.
-    - `metric:metric` - any metric.
-    - `netflow:network` - any netobserv network event.
-    - `log:LOG_TYPE` - LOG_TYPE must be `application`, `infrastructure` or `audit`
+
+The format of the goal class is experimental and may change. The valid goal classes are:
+
+[horizontal]
+`k8s:__resource[.version.[group]]__` ::  Kind of Kuberenetes resource. For example `k8s:Pod` or `k8s:Deployment.apps.v1`.
+`alert:alert`:: Any alert.
+`metric:metric`:: Any metric.
+`netflow:network`:: Any network observability event.
+`log:__log_type__`:: Stored logs,  __log_type__ must be `application`, `infrastructure` or `audit`
 
 == Optional signal stores
 
-The panel will show the resources and signals that are installed for your cluster.
-Kuberenetes resources, alerts and metrics are always available in OCP.
-Other signals are optional: logs or network flow events will only appear if Openshift Logging or Network Observabilty are installed.
+The troubleshooting panel relies on the observability signal stores installed in your cluster.
+Kuberenetes resources, alerts and metrics are available by default in an OCP cluster.
+Other types of signal require optional components to be installed:
+
+- Logs: "Red Hat Openshift Logging" (collection) and "Loki Operator provided by Red Hat" (store)
+- Network Events:  "Network Observability provided by Red Hat"  (collection) and "Loki Operator provided by Red Hat" (store)