Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mark a clear "getting started" path #297

Open
Tracked by #294 ...
dwelsch-esi opened this issue Nov 5, 2024 · 2 comments · May be fixed by #305
Open
Tracked by #294 ...

Mark a clear "getting started" path #297

dwelsch-esi opened this issue Nov 5, 2024 · 2 comments · May be fixed by #305
Assignees

Comments

@dwelsch-esi
Copy link

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: Remove obsolete websites #296.

@andoriyaprashant
Copy link
Contributor

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
Copy link
Author

dwelsch-esi commented Nov 18, 2024

  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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants