Move instructional material from Concepts to User Guide

[dwelsch-esi]

FEATURE REQUEST: Move instructional material from Concepts to User Guide

Overview

Currently, instructional information is in the User Guide, but some procedures have been embedded in the "Concepts" section. These procedures should be in one place so that users can "shop" in one place for instructions on what they need to do. You can then provide links from the procedure to the relevant Concept, and vice versa.

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

Here's a suggested course of action for each subsection in Concepts:

Concept	Documentation change
ChaosHub -> Prerequisites, Connecting to a Git Repository using ChaosHub	Move to User Guide -> Connecting to a Git Repository
ChaosHub -> Syncing a ChaosHub	Move to User Guide -> Syncing a ChaosHub to GitHub
ChaosHub -> Editing a ChaosHub	Move to User Guide -> Editing a ChaosHub (expand these instructions)
ChaosHub -> Chaos experiments and experiments in a ChaosHub -> View the PreDefined Chaos Experiments	Move to User Guide -> Viewing Predefined Chaos Experiments
ChaosHub -> Chaos experiments and experiments in a ChaosHub -> View the Chaos faults, View the fault details	Move to User Guide -> Viewing Chaos Faults
ChaosHub -> Disconnect a ChaosHub	Move to User Guide -> Removing a ChaosHub
Chaos experiment -> Prerequisites, Defining and executing a chaos experiment	Move to User Guide -> Executing a chaos experiment
Resilience Probe	This seems to be conceptual information, but corresponding procedures should certainly be written. Reserve the word "Prerequisites" for conditions that must be met before doing a procedure. For conceptual information, instead say "Related concepts".
User management	This section correctly provides conceptual information and points the reader to the corresponding procedures in the User Guide. Model the other sections after this.
Projects -> Prerequisites	Again, don't overload the term "Prerequisites"; say "Related concepts".
Collaborate with teams	Again, good conceptual overview with pointers to procedures. Don't change, but rename so that the title of the section is a noun, such as "Team collaboration" (suggesting information rather than task information).
GitOps	"Prerequisites" to "Related concepts".
Authentication	"Prerequisites" to "Related concepts".

[andoriyaprashant]

Hello @namkyu1999 I would like to work on this issue. Could you please assign it to me

Thank you

[namkyu1999]

sure @andoriyaprashant

[andoriyaprashant]

Hello @namkyu1999

Sir, I have a confusion: for cases like “ChaosHub -> Prerequisites, Connecting to a Git Repository using ChaosHub,” should I create a new file under the User Guide (e.g., user-guides/connecting-git-repo.md), or is there a preferred place to consolidate such content? Similarly, for the other sections listed (e.g., "Editing a ChaosHub", "Viewing Chaos Faults"), should I create new files for each or place them elsewhere in the User Guide?

[namkyu1999]

Hello @namkyu1999

Sir, I have a confusion: for cases like “ChaosHub -> Prerequisites, Connecting to a Git Repository using ChaosHub,” should I create a new file under the User Guide (e.g., user-guides/connecting-git-repo.md), or is there a preferred place to consolidate such content? Similarly, for the other sections listed (e.g., "Editing a ChaosHub", "Viewing Chaos Faults"), should I create new files for each or place them elsewhere in the User Guide?

Could you please provide more details @dwelsch-esi ?

[dwelsch-esi]

@andoriyaprashant Yes, Go ahead and create a new file if there is currently no topic in the User Guide for a page that needs to be moved. The idea is that the moved content is a separate procedure that a user should be able to look up in the User Guide.

There might be cases where this is a little bit of a judgement call. For example, this item:
ChaosHub -> Chaos experiments and experiments in a ChaosHub -> View the Chaos faults, View the fault details
might require its own new page, or it might become part of the existing page "Observe Chaos Experiment". It depends on whether you think the moved content is a standalone procedure or part of the existing procedure.

[andoriyaprashant]

Hello @namkyu1999 Sir, please review my pull request #315 If there are any changes required, please let me know
Thank you