Documentation Improvements

[syhol]

Let me start by saying, the documentation pages are really good and I can tell a lot of effort and expertise has gone into it. The following is based on a mix of my experience of learning Mise and issues I've seen others encounter.

Issues

I encountered 2 main problems that I think could be improved for users discovering Mise for the first time:

• I feel like its missing a good one-pager to demo the core features and use cases
• I find it hard to navigate the page structure and find what I'm looking for

Missing a good one-pager

I believe a better one-pager intro could not only help adoption but also reduce support requests and increase the usage of lesser used features. Many people have short attention spans and hate reading, so its critical they learn about core concepts as quickly as possible before they stop reading and start tinkering. You could say that Getting Started or Demo are currently filling this role, but I think they both have some issues.

Getting Started

1. A little into the page it offers you the choice about activate vs shims vs none. Most people new to Mise won't want to make choices like this right away since it requires research to understand the consequences.
2. There is very little explanation about what activate actually does at this point. It doesn't need to be in-depth like the FAQ, just something like "it updates your env vars and path every time your prompt is run to ensure you use the correct versions"
3. 2/3rd of the page is filled up with: Alternate Installation Methods, Shells, and Uninstalling. I think it makes sense to link to this content in other pages but for the majority of users this is only adding noise and making them want to leave the docs or search for more examples.
4. It doesn't demo many of what I would consider the primary features: environments, tasks, or other ways of using mise in scripts (shebangs, env, shims)

Demo

1. Its not obvious that ~/myproj has a mise config file in it, without this config the demo would behave differently. This might mislead users
2. It doesn't use the recommended install method https://mise.run
3. It doesn't mention that activate should normally be put in an rc file
4. It doesn't demo many of what I would consider the primary features: environments, tasks, mise exec, or other ways of using mise in scripts (shebangs, env, shims)
5. Terminal videos are nice but I can imagine some people wanting a more static format where they can read at their own pace

Page Structure

Once I've found the page I'm looking for, the content is really good. However I found the navigation menu to be confusing for a few reasons, causing me only discover pages days after I needed them:

1. The first 15 nav links have no structure, when scanning what page to read next I struggle to pick out a good one among all the options. To pick a few: Paranoid, Coming from rtx, and How I Use mise are all quite specific and I would put in a less prominent position. I imagine those top links will be the ones that get clicked the most by new users.
2. The pages for Plugins, Registry, and Languages are spread around in a bunch of different places, yet in my mind are all very Dev Tools specific. Having these 3 in very different places can be confusing, and got me thinking there was a difference between a Language and a Plugin. I also got them confused with backends a few times.
3. Clickable top level parent pages. I didn't realise Dev Tools, Environments, Tasks, and CLI Reference were clickable links for about a week. I blame this in part to my stupidity but also to the theme, they don't look clickable to me. This is compounded by the fact the Languages and Internals are not links.
4. Profiles adds important missing context about how config files can be setup. There is a link to it from Configuration but I missed it. Also I don't see what Profiles has to do with Environment Management, but thats just an opinion.

Solutions

I'll post some ideas for solutions below, please feel free to pick them apart.

[syhol]

Proposed Page Structure

Summary of changes

• Top level groups are no longer links and have been replaced with X Introduction
• Some new top level sections have been created to organise the top section
  • Guides - The main section new users would read to learn about how to use Mise
  • About - Project related info
  • Integrations - For integrating Mise into other systems
  • Advanced - To tidy away some pages that aren't aimed for new users
• Tips & Tricks content has been moved into more specific areas
• The languages/plugins/registry have been brought together under Dev Tools

The Page Structure

• Guides
  • Getting Started (the redesigned one-pager: mise.run + activate + use + install + exec + run)
  • Installing Mise (Moved from Getting Started -> Alternate Installation Methods + Shells)
  • Using Mise in a shell (activate + shims + mise shell)
  • Using Mise in a script (mise run + exec + mise env + Merge Tips & Tricks -> Shebang)
• Configuration (Merge Environment -> Profiles & Merge Tips & Tricks -> mise set into this page)
• FAQs (Merge Tips & Tricks -> Rosetta into this page)
• About (Merge Demo video into this page)
  • Team (Moved from top level)
  • Contributing (Moved from top level)
  • Project Roadmap (Moved from Internals)
• Dev Tools (No longer a link)
  • Dev Tools Introduction
  • Plugins (Moved Languages from top level and renamed)
    • Plugin Registry (Moved Registry from top level and renamed)
    • Bun
    • Deno
    • Erlang
    • Go
    • Java
    • Node.js
    • Python
    • Ruby
    • Rust
  • Aliases
  • Shims
  • Backends
    • asdf
    • cargo
    • go
    • npm
    • pipx
    • spm
    • ubi
  • Comparison to asdf
• Environments (No longer a link)
  • Environments Introduction
  • Templates
• Tasks (No longer a link)
  • Tasks Introduction
  • Running Tasks
  • Script Tasks
  • TOML Tasks
• Integrations
  • direnv
  • Continuous Integration (Merge Tips & Tricks -> CI/CD into this page)
  • IDE Integration
• CLI Reference (No longer a link)
  • Commands
  • Global Flags
• Advanced
  • Paranoid
  • Coming from rtx
  • How I Use mise
  • Internals
    • Cache Behavior
    • Directory Structure

[hverlin]

I agree with you that the top-level elements in the menu should not be links. 💯 I think it's a bit confusing as not all of them are links also.

Without breaking any links (just re-ordering the menu elements), we could have something like this:

As mentioned, some pages could be merged. I have hidden the demo in the collapsed menu of Walkthrough in the screenshot.

What do you think @jdx? I would at least suggest removing the Clickable top level parent pages

Here is the configuration I used for the screenshot:

    sidebar: [
      {
        text: 'Guides',
        items: [
          { text: "Getting Started", link: "/getting-started" },
          { text: "Walkthrough",
            link: "/walkthrough",
            collapsed: true,
            items: [{ text: "Demo", link: "/demo" }],
          },
          { text: "Continuous Integration", link: "/continuous-integration" },
          { text: "IDE Integration", link: "/ide-integration" },
        ]
      },
      {
        text: "Configuration",
        items: [
          { text: "mise configuration", link: "/configuration" },
          { text: "Settings", link: "/configuration/settings" }
        ],
      },
      {
        text: "Dev Tools",
        items: [
          { text: "Dev tools overview", link: "/dev-tools/" },
          { text: "Comparison to asdf", link: "/dev-tools/comparison-to-asdf" },
          { text: "Shims", link: "/dev-tools/shims" },
          { text: "Aliases", link: "/dev-tools/aliases" },
          {
            text: "Plugins / Languages",
            link: "/plugins",
            items: [
              {
                text: "Core plugins",
                link: "/core-plugins",
                collapsed: true,
                items: [
                  { text: "Bun", link: "/lang/bun" },
                  { text: "Deno", link: "/lang/deno" },
                  { text: "Erlang", link: "/lang/erlang" },
                  { text: "Go", link: "/lang/go" },
                  { text: "Java", link: "/lang/java" },
                  { text: "Node.js", link: "/lang/node" },
                  { text: "Python", link: "/lang/python" },
                  { text: "Ruby", link: "/lang/ruby" },
                  { text: "Rust", link: "/lang/rust" },
                ],
              },
              { text: "Plugin registry", link: "/registry" },
              {
                text: "Backends",
                link: "/dev-tools/backends/",
                collapsed: true,
                items: [
                  { text: "asdf", link: "/dev-tools/backends/asdf" },
                  { text: "cargo", link: "/dev-tools/backends/cargo" },
                  { text: "go", link: "/dev-tools/backends/go" },
                  { text: "npm", link: "/dev-tools/backends/npm" },
                  { text: "pipx", link: "/dev-tools/backends/pipx" },
                  { text: "spm", link: "/dev-tools/backends/spm" },
                  { text: "ubi", link: "/dev-tools/backends/ubi" },
                  { text: "vfox", link: "/dev-tools/backends/vfox" },
                ],
              },
            ]
          },
        ],
      },
      {
        text: "Environments",
        items: [
          { text: "Environment overview", link: "/environments/" },
          { text: "direnv", link: "/direnv" },
          { text: "Profiles", link: "/profiles" },
          { text: "Templates", link: "/templates" },
        ],
      },
      {
        text: "Tasks",
        items: [
          { text: "Task overview", link: "/tasks/" },
          { text: "Running Tasks", link: "/tasks/running-tasks" },
          { text: "TOML Tasks", link: "/tasks/toml-tasks" },
          { text: "File Tasks", link: "/tasks/file-tasks" },
        ],
      },
      { text: "FAQs", link: "/faq" },
      { text: "Troubleshooting", link: "/troubleshooting" },
      { text: "Tips & Tricks", link: "/tips-and-tricks" },
      {
        text: "About",
        items: [
          { text: "About mise", link: "/about" },
          { text: "Team", link: "/team" },
          { text: "Project Roadmap", link: "/project-roadmap" },
          { text: "Contributing", link: "/contributing" },
        ]
      },
      {
        text: "Advanced",
        items: [
          { text: "Paranoid", link: "/paranoid" },
          { text: "Coming from rtx", link: "/rtx" },
          { text: "How I Use mise", link: "/how-i-use-mise" },
          {
            text: "Internals",
            items: [
              { text: "Cache Behavior", link: "/cache-behavior" },
              { text: "Directory Structure", link: "/directories" },
            ],
          },
        ]
      },
      {
        text: "CLI Reference",
        collapsed: true,
        items: [
          { text: "CLI overview", link: "/cli/" },
          ...cliReference(commands)
        ],
      },
    ],

[jdx]

I think it's a good change

[hverlin]

Created #2891. Feel free to update of course

[syhol]

Proposed Good One-pager

With the goal to show the golden path of Mise and demo a shallow but broad set of features to display Mise' capabilities.

1. Install with curl https://mise.run | sh. Link to other page with alternative installs.
2. Activate in shell (use the nice "bash | zsh | fish" picker you have in activate mise)
3. Restart or exec shell
4. Install and use a global dependency with mise use --global
5. Create a mise config file
6. Install and use a local dependency with mise use
7. Demo the changing of versions as you CD. Mention this requires mise activate.
8. Demo mise set and show the environment variable set in the shell with env | grep X.
9. Demo mise exec with a tool not currently installed. Mention this does not need mise activate for tools or env vars set through mise.
10. Make a task
    i. mkdir -p .mise/tasks
    ii. echo '#!/usr/bin/env sh' >> .mise/tasks/start
    iii. echo 'node --version' >> .mise/tasks/start
    iv. chmod +x .mise/tasks/start
11. Run the task mise run start. Mention this does not need mise activate for tools or env vars set through mise.

This is effectively demoing the following:

• Installing and activating mise (the golden path for users)
• mise use for the basics of Dev Tools
• mise set for the basics of Environments
• mise exec for usage without activation
• mise run for the basics of Tasks

[KyleKing]

Tool Options per backend are also missing. For example, it would be good to know about extras for pipx (current pipx page, source) or the options for cargo (source). I only know about the available options from investigating this issue #2025

[KyleKing]

Currently there is a general section about Tool Options and the postinstall script, but nothing specific about the options supported per backend: https://mise.jdx.dev/dev-tools/#tool-options

[hverlin]

@syhol Started to provide some suggestions for the getting-started guide based on your comments here: #2930 (comment)

[syhol]

Amazing, that looks sweet 🙌