search

litmuschaos / litmus-docs

Documentation for the Litmus Project
https://docs.litmuschaos.io
Apache License 2.0
16 stars 79 forks source link

Mark a clear "getting started" path #297

Open dwelsch-esi opened 3 weeks ago

dwelsch-esi commented 3 weeks ago

FEATURE REQUEST: Mark a clear "getting started" path

Overview

There are at least four "getting started" links on the website. To avoid confusing users, make them all point to the same place, or relabel them so they more accurately reflect the linked content.

The idea is to funnel new users to the Getting Started page, where they can focus uninterrupted on a streamlined procedure for installing and testing the product.

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

The following links are all labeled "Getting Started" but lead to different pages:

  1. The Get Started button in the Product landing page banner menu points to the GitHub repo.

    Recommendation: Re-label the button "Learn more" or "Go to documentation".

  2. The Get Started button on the Product landing page points to the GitHub repo.

    Recommendation: Re-label the button "Learn more" or "Go to documentation".

  3. The Get Started button on the Doc landing page points to ChaoCenter installation.

    Recommendation: Re-label the button "Learn more" or "Go to documentation". Or, remove this button since the very next section starts with a link to the installation documentation.

  4. The Getting Started link on the Doc landing page points to What is Litmus?.

    Recommendation: Leave as is. But, reorganize the Installation/Getting Started section in the documentation table of contents (see the next item).

  5. The Get Started table of contents (TOC) entry in the Doc page left-side menu expands the section's options in the TOC.

    Recommendation: Remove the "Resources" section (that material is covered elsewhere, in "Architecture" and "Concepts"; add a link to that explanation instead). The "Installation" page is a good workflow for beginners to get through installation, configuration, and starting to use the product. Move the contents of the "Installation" page up so that it's a standalone entry called "Getting Started". Move that section to the top of the TOC.

  6. The Getting started tutorial is a standalone tutorial that provides an end-to-end path for a beginner to install, validate, and run Litmus and execute a chaos experiment.

    Recommendation: Link to the tutorial from the main website. Also, see the issue about updating and maintaining the tutorials and other Litmus-branded websites: https://github.com/litmuschaos/litmus-docs/issues/296.

andoriyaprashant commented 1 week ago

Hello @namkyu1999

I’m currently working on this issue. I have a couple of questions:

  1. While removing the Resources section as recommended, I encountered warnings during debugging:
[WARNING] Docs markdown link couldn't be resolved: (../getting-started/resources.md) in E:\Open source projects\litmus-docs\website\versioned_docs\version-3.12.0\user-guides\uninstall-litmus.md for version 3.12.0
[WARNING] Docs markdown link couldn't be resolved: (../getting-started/resources.md) in E:\Open source projects\litmus-docs\website\versioned_docs\version-3.12.0\user-guides\setup-without-ingress.md for version 3.12.0

Should I update these links to point to an alternative page, or would you recommend removing them altogether?

  1. Regarding the Getting Started tutorial, it’s mentioned that we need to link it to the main website. Could you please clarify where exactly this link should be added?

Looking forward to your guidance Thanks

dwelsch-esi commented 1 week ago

  1. I think I'd move the ChaosCenter section from Resources into the Concepts section. This would also solve the problem that ChaosCenter is referred to in other Concepts topics (Chaos Experiment, Authentication in ChaosCenter) without providing or pointing to a description of it.

  2. I'd put it in the docs table of contents. You can also mention it in the text where appropriate, for example in the "What's Next" section of the Getting Started workflow.