Manual needs to be more helpful, friendly, and better organized

[matklad]

rust-analyzer manual is pretty long: https://rust-analyzer.github.io/manual.html

It's useful as a reference, but is quite intimidating if you want to learn the tool. We should improve this, both in terms of logical organization, and in terms of HTML&CSS rendering. I am not experienced with it, so help would be much appreciated.

I think ideally the manual shows a short pit of success, while giving the links to in-depth reference material. Here's a structure I have in mind:

First is quick start, which suggests choosing an editor (VS Code, Vim, Emacs). For a specific editor, we have a single blessed setup. After the setup, we have a short section show-casing the most important features (worksapce symbol, go to definiton, extend selection, running tests, triggering assists). This should be duplicated for editor, and serves two purposes -- teaches about the features and allows the new user to verify if the stuff is working. Aftre quick start and show case, we show how to configure rust-analyzer in the specific editor. After that, we show alterntive setups

After per-editor quick start, we probably want to re-create show case, with the emprasis on how it looks and why it is useful, rather than on which shourtcur do you use to trigger this.

After universal show-case, we should have an index of features, which leads to specific pages for diagnostics, assists, etc.

After that, we should have troubleshooting and other stuff.

As I've said, I am not an expert at this: if you think you see a better way to do this, feel free to suggest. The source for manual lives here: https://github.com/rust-analyzer/rust-analyzer/tree/master/docs/user.

It is render to a web document here: https://github.com/rust-analyzer/rust-analyzer.github.io

The code to move the manual from the first place to the second place is here: https://github.com/rust-analyzer/rust-analyzer/blob/91bfa4b154a9776a57f25071f03e68d4f9f5ef35/xtask/src/release.rs#L25-L50

[Jesse-Bakker]

Some notes:

1. The index at the top should either be more hierarchical and collapsed by default, or the manual needs to be split over several pages. Reasoning: when I'm trying to find something, it's easier to go:

• quickstart? no. installation? no. features? yes! features->magic completion? no. ...10 other features...? no. features->joinLines? yes!
  than:
• quickstart? no. installation? no. magic completion? no. ...10 other features...? no. joinLines? yes!
  because I know I will find what I'm looking for in that list. Also, finding something after a long list is now near impossible.

2. Besides a list of settings, also present the relevant settings with their corresponding feature. When I see a feature I really like, I want to know how I can customize it. An example is joinLines. I like to have it, but I also want to know how to turn off moving a line into the else block of an if (see JoinLines discover ability  #9492)

[matklad]

Besides a list of settings, also present the relevant settings with their corresponding feature.

That's a great point! We need to incorporate feature configs into our // Feature: pseudo doc-strings.

[tsoutsman]

Could the manual maybe be remade with mdBook? The step-by-step guide suggested by @matklad could be implemented with links creating a choose your own adventure style experience. It wouldn't be as flashy as a custom website but it would definitely be less burdensome to both create and maintain. It's also in line with the rest of the Rust ecosystem. Currently, the docs are in AsciiDoc which is relatively similar to Markdown, decreasing the work needed to migrate.

I'm obviously not an active member of rust-analyzer so I could be missing something or making incorrect assumptions. Is there a specific reason this current setup was chosen?

[matklad]

I don't have a super-strong opinion with respect to tech stack -- we can switch to mdBook if folks find that more convenient.

I do think thought that the book format isn't the best for this info:

• for quick start page, we need a "landing page" experience -- a new user should need only a (well-organized) screenful of data to learn how to get started and where to get more info.
• for features, we need a view which lists all assits/diagnostics/etc on the single page, so that its easy to ctrl+F a specific feature, and that it's easy to accidently notice a feature that you need, but don't even know that you need.

Both feel very different than mdBook topical split into chapters.

[flodiebold]

• we need a view which lists all assits/diagnostics/etc on the single page, so that its easy to ctrl+F a specific feature

mdBook has a full-text search bar at the top, so I think that use case would be covered.

[matklad]

https://emacs-lsp.github.io/lsp-mode/tutorials/how-to-turn-off/ <- that's a great way to show what features are available.

[joshrotenberg]

I've started a Pull Request for this here: #10791

I wanted to address some of your ideas/my approach, easier to respond here rather than copy/pasting into the above.

rust-analyzer manual is pretty long: https://rust-analyzer.github.io/manual.html

Agreed. Lots of information in there! I'm hoping I can help make it easier to navigate.

It's useful as a reference, but is quite intimidating if you want to learn the tool. We should improve this, both in terms of logical organization, and in terms of HTML&CSS rendering. I am not experienced with it, so help would be much appreciated.

I think just moving the navigation over makes a world of difference which makes mdbook a decent option (but please let me know if you disagree).

I think ideally the manual shows a short pit of success, while giving the links to in-depth reference material. Here's a structure I have in mind:

Agreed. Personally, I like the shortest path to get something working, and then I'll go back for more depth. If that shortest path is the first thing the user sees or is at least very easy to find (like a Quickstart link way up at the top) that seems like a win.

First is quick start, which suggests choosing an editor (VS Code, Vim, Emacs). For a specific editor, we have a single blessed setup. After the setup, we have a short section show-casing the most important features (worksapce symbol, go to definiton, extend selection, running tests, triggering assists). This should be duplicated for editor, and serves two purposes -- teaches about the features and allows the new user to verify if the stuff is working. Aftre quick start and show case, we show how to configure rust-analyzer in the specific editor. After that, we show alterntive setups

This could all go in the aforementioned top level Quickstart page that's easy to find. Maybe this is all a single document, or maybe we have a hierarchy up top for the latter pieces you mentioned.

After per-editor quick start, we probably want to re-create show case, with the emprasis on how it looks and why it is useful, rather than on which shourtcur do you use to trigger this.

After universal show-case, we should have an index of features, which leads to specific pages for diagnostics, assists, etc.

After that, we should have troubleshooting and other stuff.

As I've said, I am not an expert at this: if you think you see a better way to do this, feel free to suggest. The source for manual lives here: https://github.com/rust-analyzer/rust-analyzer/tree/master/docs/user.

I've essentially kept the same structure as the current manual with my mockup, but I'm happy to move things around if that structure doesn't fit anymore.

It is render to a web document here: https://github.com/rust-analyzer/rust-analyzer.github.io

The code to move the manual from the first place to the second place is here:

https://github.com/rust-analyzer/rust-analyzer/blob/91bfa4b154a9776a57f25071f03e68d4f9f5ef35/xtask/src/release.rs#L25-L50

We can possibly move this into the CI, or just rework it to use the mdbook binary or API. I think the former is the most common approach.

[joshrotenberg]

• for quick start page, we need a "landing page" experience -- a new user should need only a (well-organized) screenful of data to learn how to get started and where to get more info.

I think we can do this with mdbook, we just need to make it very easy to get to ASAP. See my comments above, but I think putting a Quickstart section either in the main page or as a top level item gets this pretty close to what you're asking for.

• for features, we need a view which lists all assits/diagnostics/etc on the single page, so that its easy to ctrl+F a specific feature, and that it's easy to accidently notice a feature that you need, but don't even know that you need.

Right now my mockup has them as separate md files, but the full list should alway be ctrl+fable on any page because of the mdbook layout. mdbook also has a good built in search.