A lot of stutter in our left navigation

[dprotaso]

I was wondering if we should aim to clean up our navigation a little bit. I notice there is quite a bit of 'stutter' among the sections and subsections

Secondly, some navigation items appear to be 'nodes' that only group together a bunch of subtopics. This leads to excessive clicks to find content.

I don't know what the right solution is - but am looking for ideas.

[dprotaso]

cc @iRaindrop @evankanderson for input

[evankanderson]

Yes! I think we may need to write and/or refactor content to improve the navigation to allow us to reduce this stutter.

[dprotaso]

I also see that material mkdocs supports having bolded headers - some of them can be pages like 'Tutorials' and 'Changelog'. 'Getting Started' doesn't have a link.

[dprotaso]

Though - I guess you lose the indentation

[codeEvolveZenith345]

Hi @evankanderson @dprotaso

Is this issue still open for contribution ? there is a linked PR but it is dated earlier than the issue.

[evankanderson]

Hi,

This is still open for contribution. The referenced PR was being asked to avoid introducing more stutter, rather than cleaning up existing instances in the navigation.

[evankanderson]

(you can use /assign to assign an issue to yourself)

[codeEvolveZenith345]

/assign

[codeEvolveZenith345]

Hey @evankanderson Are there any specific reference that I can follow in my implementation? Any design pattern that should be followed...as other CNCF projects. Once I have clarity over the design pattern I can move ahead to resolving this nav issue.

Thank you.

[codeEvolveZenith345]

Hi @dprotaso @evankanderson I need confirmation, Is the expected outcome supposed to align with patterns/practices in the material/mkdocs mentioned.

Please clarify and I will fix it! Thank you.

[evankanderson]

I'm not sure that Dave or I have thought deeply about how to solve this problem -- Material for Mkdocs (and the nav plug-in we use) have a number of tools and modes for specifying the navigation tree. The main problem is using those tools consistently in our documentation.

At a minimum, Dave is pointing out that we have a number of places where the navigation looks like:

Installing Knative   >
   Installing Knative With YAML
   Installing Knative With Operator

Where "Installing Knative" is repeated in each sub-topic, making it hard on smaller devices to even see the distinguishing details.

[codeEvolveZenith345]

@evankanderson Would it be okay to truncate the common substring from parent to child...in the nav display?

I might be wrong, but it seems a simpler fix...

[codeEvolveZenith345]

Would it be okay to truncate the common substring from parent to child...in the nav display?

If not this, then I guess it would require significant edits, for relevant naming....

[iRaindrop]

The current Nav has it shorter with "Install":

Installing Knative
   Install Knative With YAML
   Install Knative With Operator

In this case, it's good to keep the gerund "Installing" as the node title, and the base form of the verb for the child titles.

It's not always the same meaning going back and forth. "Install" sounds like a directive, "Installing" sounds like a procedure you can do at any time.

I did a search of "ing" in the Nav.yml and that's the only occurrence of adjacent titles of the same verb with different forms.

[codeEvolveZenith345]

Hi @iRaindrop Thank you for the idea!, I found quite a few (40+) stutter instances in Nav.yml. like in

Install with Knative Operator:
          - Install by using the Knative Operator: install/operator/knative-with-operators.md
          - Install by using the Knative Operator CLI plugin: install/operator/knative-with-operator-cli.md
          - Configuring Knative using the Operator: install/operator/configuring-with-operator.md
          - Configuring Knative Serving CRDs: install/operator/configuring-serving-cr.md
          - Configuring Knative Eventing CRDs: install/operator/configuring-eventing-cr.md

---

I am attaching some examples/suggestions, It will require significant edits I guess...🤔 please take a look @dprotaso @evankanderson

1. Use Bold Section Headers for Top-Level Organization Convert grouping-only nodes to bold headers:

# BEFORE (Current)
- Installing Knative:
    - Overview: install/README.md
    - Install Knative with YAML:
        - YAML-based installation: install/yaml-install/README.md
        - Install Knative Serving:
            - Install Serving with YAML: ...
            - Knative Serving installation files: ...

# AFTER (Flattened with bold headers)
- Installing Knative: install/README.md  # Make this a landing page
- Install with YAML:
    - Serving: install/yaml-install/serving/install-serving-with-yaml.md
    - Serving installation files: install/yaml-install/serving/serving-installation-files.md
    - Eventing: install/yaml-install/eventing/install-eventing-with-yaml.md
    - Eventing installation files: install/yaml-install/eventing/eventing-installation-files.md
- Install with Operator:
    - Using Operator: install/operator/knative-with-operators.md
    - Using Operator CLI: install/operator/knative-with-operator-cli.md
    - Configuring with Operator: install/operator/configuring-with-operator.md

2. Remove Redundant Keywords

Strip "Install", "Knative", "with" when context is clear:
yaml# Under "Installing Knative" parent:
- YAML Installation:        # Not "Install Knative with YAML"
    - Serving               # Not "Install Knative Serving with YAML"
    - Eventing              # Not "Install Knative Eventing with YAML"
- Operator Installation:    # Not "Install with Knative Operator"
    - Setup                 # Not "Install by using the Knative Operator"
    - CLI Plugin            # Not "Install by using the Knative Operator CLI plugin"

3. Enable navigation.indexes in mkdocs.yml This makes parent sections clickable landing pages, eliminating "node-only" sections:

theme:
  features:
    - navigation.indexes
    - navigation.sections

[codeEvolveZenith345]

@dprotaso @evankanderson @iRaindrop

We can also focus on these few sections that are accessed more frequently by users to have a minimal fix:

1. Installing Knative
2. Functions
3. Configuring Knative
4. Services
5. Event Sources