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

Provide more essential documentation on how to navigate LunarVim on quickstart page #217

Open
avalonv opened this issue Aug 20, 2022 · 3 comments
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers help wanted Extra attention is needed

Comments

@avalonv
Copy link

avalonv commented Aug 20, 2022

Currently, navigating certain key components of LunarVim's interface require familiarity with external plugins. This by itself is not a problem, the problem is that there isn't an easy way for a new user to find out what some of those plugins are, and thus read their documentation, leading to an artificially steep learning curve early on.

This thread summarizes this issue: a new user has no clue how to use the default file explorer bundled with LunarVim because they're unfamiliar with the plugin it is based on. There's nothing to indicate the explorer on the screen is nvim-tree, and although there's a simple keybinding to list other keybindings, it's not shown anywhere.

As @rebuilt mentioned in the thread, it's unreasonable to expect this project's website to host the documentation for each and every core plugin, as these plugins are updated all the time. I think a good compromise for an IDE however, would be to describe the default UI components used for navigation and link to their respective documentation pages directly on the quickstart page.

@avalonv
Copy link
Author

avalonv commented Aug 20, 2022

Currently the process for finding the documentation for how to use telescope or nvim-tree, two essential parts of LunarVim's UI, goes a bit like this: Getting Started -> Installation -> Quickstart -> Under "Next Steps", there's a page pointing to plugins, which explains how to configure them -> From here a user could reach Core Plugins List, which links to the documentation.

Imo, this is a rather unintuitive way of learning how to use a program, as:

  1. It's too many steps, which makes it more likely users will look for help elsewhere (the issues page), when all the relevant documentation is technically on the website already.
  2. You have to deduce the core UI's function based on their descriptions in a rather long list, instead of being told what does what from the beginning.
  3. You're taught how to configure components in the program before being shown what they do. Furthermore, many of these components have unintuitive names (telescope), so seeing examples in the configuration doesn't alleviate 2.

IMO, for more advanced things like linters and git integration and such, where the user is likely to open a configuration file to configure project specific options anyway, point 2 is not a problem, there are better ways to convey information, but for their scope it's perfectly fine. However for the built-in aspects of the interface, for what comes bundled with the IDE itself and is necessary to navigate it, it's confusing to have to read through a sub-page to the "plugins" page to understand how, for example, the "open a file" dialogue works, when you aren't familiar with what "telescope" is, and thus can't know whether "teslecope" is a plugin or not.

Summarizing what these key UI components are (and where to find their documentation), in a "Interface & Navigation", or "Using LunarVim", subsection of quickstart, perhaps as a standalone page, would significantly alleviate most of those problems, and make it more accessible for people that aren't already familiar with vim as an IDE.

@kylo252 kylo252 added documentation Improvements or additions to documentation good first issue Good for newcomers help wanted Extra attention is needed labels Aug 20, 2022
@rebuilt
Copy link
Contributor

rebuilt commented Aug 21, 2022

I previously wrote sections like this in the README but they were removed by Chris for brevity. Sample here: https://github.com/LunarVim/LunarVim/blob/b3cd29f86369c0f61c467ccea1510b6fb6773c9d/README.md#getting-started

My understanding of the decision for removing these sections is that:

  • there's already too much to read
  • code examples are preferable to long prose
  • it's hard to keep these sections updated as the project changes
  • the longer the text, the less likely it is for anyone to actually read it.

That said, I'm all for adding information geared towards newer users as long as it's brief.

@avalonv
Copy link
Author

avalonv commented Aug 27, 2022

Apologies for the late reply. I personally think the "Getting Started" section makes it much more accessible than the current README. Perhaps a compromise could be reached, with that section being re-added, or with its text featured prominently at the top of the Quick-start page of the website?

@LostNeophyte LostNeophyte mentioned this issue Jan 16, 2023
9 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

3 participants