Revise the User Guide procedures

[dwelsch-esi]

FEATURE REQUEST: Revise the User Guide procedures

Overview

The User Guide contains stepwise procedures, but many of these could be written more clearly. We think it's worth reviewing all the procedural documentation on the site (the install procedures and the procedures in the User Guide) and rewriting them using a template to ensure they're complete and consistent.

Some guidelines for writing procedures:

• Ensure that tasks are complete. For complex procedures, it's OK to link to
  sub-procedures or (usually better) put preliminary tasks in the Prerequisites
  section.
• Number the steps in the main procedure. Do not combine steps. If a step requires two distinct actions,
  split it into two steps.
• A basic outline for a procedure should include:
  1. Introduction - provide context for the task.
  2. Prerequisites: System requirements, operating systems, network, databases -
     anything that needs to be in place before for you to perform the task that's being documented.
  3. Step by step instructions: Number the steps. Provide only one action per
     step. An action is a CLI command, GUI action -- anything that must be done
     before moving on to the next step. For CLI commands, file contents, and so
     on, provide copyable text. Don't combine steps,
     especially when they must be done in sequence.
  4. Results (optional; not needed if the results are obvious): What happens
     when the procedure is successful. Can include an instruction for how to
     verify results.
  5. Next steps: Links to one or more procedures that the user might reasonably
     want to do next. This might be a link to the next step in a larger procedure,
     or to options that are available now that the task is finished.

Context

This issue tracks recommended changes resulting from an analysis of the Litmus Chaos
documentation commissioned by CNCF. The analysis and supporting documents are
here: https://github.com/cncf/techdocs/tree/main/analyses under
0013-litmuschaos.

Possible implementation

Below is an example. This is a rewrite of a procedure from the User Guide, using the template above.

---

Observing a chaos experiment

Visualizing an experiment is important while doing chaos engineering, enabling you to discover and inspect changes that occur during execution of a chaos experiment.

The real-time data and status of the chaos experiments can be observed in ChaosCenter. Pod logs, chaos experiment status, and chaos results can be viewed.

Prerequisites

To observe a chaos experiment:

• ChaosCenter must be installed and running.
• You are logged into the ChaosCenter GUI.
• You have saved and run one or more Chaos Experiments.

Procedure

1. Select an experiment

In ChaosCenter, go to the row representing the experiment you want to view on the Chaos Experiments page and select a highlighted experiment run box from the heatmap in the RECENT EXPERIMENT RUNS column.

2. Observe the experiment information

The experiment run execution page displays a real time graph of the experiment.

3. View step details

Click a step in the experiment graph to view details of that step.

Results

If the chaos experiment execution has completed, the ChaosResult for the ChaosEngine pods is available.

Next Steps

To better understand chaos experiment results, see:

• Explore Probes
• What is a Chaos Experiment