Documentation and onboarding new users

Plugin Development
#1

Hi all,

Longform post inbound. Thoughts and opinions are my own.

I’ve been thinking a lot about accessibility (to newcomers) in Neovim. Simultaneously, I think there is growing frustration from a portion of the userbase about the state of plugin documentation in the neovim ecosystem. There are several axes on which we can discuss this, so let’s jump right in.

Priors

Plugins usually can have, at most, a single visible readme. This readme, in a way, is the face and entrypoint of the project. It may include images, GIFs, video, in addition to both “Quick Start” and detailed dissections of the various configuration options for a given project. Occasionally, information is also contained in a wiki (often hosted on github) referenced by the readme. In the case of vim, there is often the vimdoc, which can be semi-automatically generated from the readme via various plugins.

Who is the target userbase for neovim? How does this affect documentation?

Given that there is a single chance to get a readme “right”, it’s important to consider the target audience because this affects how we should think about documentation. I’d like to take a brief digression to describe two types of users:

  • User class A: This user maintains their own vim configuration. They use (neo)vim, find a pattern they repeatedly execute during the course of their work, and install plugins to address this repetition. The user goes on discourse/google/reddit to find references to the “latest” plugins to improve this aspect of their workflow. This user may maintain plugins themselves and is familiar (to some degree) with the internals of vim. This user reads the manual, and perhaps even the source code, when they install a new plugin. This user is easy for plugin authors to write documentation for, because most often plugin authors fall into user class A.

  • User class B: This user may maintain their own vim configuration, or use a larger framework (LunarVim, NvChad, etc.). They may have predominantly used vscode in the past, and be used to a declarative GUI driven configuration schema. Instead of seeking out a particular enhancement to their workflow by adding a particular plugin, they instead are concerned about the holistic experience for their language of choice (How do I configure neovim as a Typescript IDE?). This user often expects tight cohesion across many plugins, and often times wants to slot these plugins into their configuration framework of choice. This user is most likely to view the readme as the final source of truth for configuring their plugin.

Most plugin authors, I would wager find it easier to communicate with User class A, however, as the neovim ecosystem grows, I think it is critical we find ways to communicate better with user class B.

General guidelines for a good readme

Before delving in on how we can better accommodate user class B, lets discuss what makes a good readme. I’m codifying this here for the community’s sake as much as my own, as I’ve historically struggled to write good documentation as well. Here are some things I believe to be true (some may be patently obvious):

  • Motivate the plugin immediately – a user should know roughly what your plugin does in the first few lines
  • Include a getting started guide after the motivation – a user should be able to get started using your plugin in less than 30 seconds, if possible
  • Grammatically correct – this is often hard to do, especially if you are a single plugin developer. ltex-ls, vale, and :help spell can be invaluable here
  • Avoid jargon if possible
  • Include the most common pitfalls of your plugin with a small troubleshooting section (if application)
  • Link to the wiki, contributing guide, and other useful resources
  • Link to a support forum, or matrix room where users can ask questions
  • You should have 2-3 potential users proof your readme, try to use your plugin, and provide feedback. Ask on #neovim:matrix.org or here on discourse if you cannot find anyone.

While I think the above are universally true, the following are opinions, which I would love to hear community feedback on:

  • The readme should generally not be exhaustive, especially in length. Historically, I’ve found that even having a long readme signals some level of unapproachability that turns off user class B. I would say generally 500 lines is a good limit.
  • The readme should be limited in scope to your plugin, integrations with other plugins should be referenced/documented in the wiki.
  • Generally, the plugin author is both the best and worst person to write the documentation for a plugin. They are generally the “best” in the sense that they probably have the most comprehensive knowledge of the plugin. They are generally the “worst” in the sense that they are likely A) a proficient vim user, B) capable of reading the source code to understand available options/configuration, and C) not a new user of the plugin, and have a large body of prior knowledge.

An aside on youtube tutorials and blog posts

One thing that I think is especially problematic is the rise of youtube tutorials and blog posts as the primary source of truth for configuring plugin sets.

Unlike a project’s wiki, which is somewhat central and maintained by presumably at least the project’s authors, youtube tutorials grow stale and authors rarely take down and reupload videos with new information. I understand there are practical considerations here, viewership numbers, video monetization, and accessibility (some users do not like reading documentation) are all compelling reasons to prefer video format.

Worse still, blog/reddit posts often contain “snippets” that can be copy/pasted by users. This creates a game of telephone, with snippets often suffering from bitrot. Users rarely, if ever, update old comments.

Catering to user class B in documentation

I think the points I made generally speaking about writing readmes apply here. The readme should be short, to the point, include a quickstart guide, and include various debugging steps and troubleshooting resources. Steps which may seem obvious (installing or requiring system packages, managing system environmental variables, writing small bits of code as configuration) are likely points of failure.

I’ll use the built-in client as an example here.

A worked example: the lspconfig readme

Let’s take the lspconfig readme as it was 1 year ago and go through the issues:

  • It’s unclear what LSP is and why users should care about it
  • There’s no quickstart guide
  • installation is 20+ lines into the readme
  • there’s implemenation details/degenerate solutions to overriding server configuration
  • the readme is extremely long, because it includes auto-generated details for configuration each language server in the main body
  • there’s no recommended configuration (keymaps, avialable functions, etc)
  • there’s implementation details (function signature of setup {}) immediatley exposed to the user

Let’s compare this to the current readme. Of course, improvements (as PRs) welcome.

  • Both the plugin and the utility of LSP is explained immediately.
  • Installation instructions are provided
  • A quickstart guide with the exact commands to have a working language server installed are included
  • Keybindings/recommended settings are illustrated
  • There’s a wiki, with a complete example configuration
  • references to external plugins that provide expected user functionality (autocompletion, snippets) are provided in the wiki and linked in the readme
  • it’s short
  • common debugging steps are included

Provide multiple steps/resources for user debugging

Some things I’ve found helpful:

  • providing a minimal vim configuration that self-bootstraps, provides messages that indicate to the user the steps required for debugging
  • providing a more full featured configuration that shows how your plugin integrates with other plugins
  • providing a containerized environment that allows users to rapidly see what your plugin “should” perform like, eliminating any issues in their configuration. Try, for example, podman run --rm -it quay.io/nvim-lsp/try.nvim:nightly-c to run lspconfig in a container using the kickstart.nvim configuration (open a c file in the repo with neovim).
  • using github forms that link to support forums for user questions (hence why I created this discourse)

Workflow documentation, or the need for cookbooks

One thing this does not directly address is the need for system level views as to how various plugins work together. Often times user class B wants to understand how various plugins come together to replicate functionality they may be used to, perhaps it includes snippets, autocompletion, auto-imports, a specific UX around diagnostics, their linter of choice, etc.

A new class of documentation, language guides

I think it would be great to create a set of language guides that could receive community contribution, centering around a set of workflows, demonstrating how plugins associated with a language work together.

  • The primary difference between this and reddit/youtube guides would be that I would like to find a way to loop in plugin authors, and have them directly contribute/update the portions of the guide that pertain to their plugin.
  • I would love to ship these along with containerized test environments like try.nvim that include the neovim configuration along with the language tooling and an example repo of choice.
  • I created a new github organization for this purpose: nvim-language-guides · GitHub, reach out to me if you’re interested in the guide/providing a test container to go along with it.

What can you do about it?

I think now would be a great time to pick your favorite neovim plugin, reach out to the author asking if they would welcome documentation updates, and then file a PR suggesting some changes.

More projects should start offering “cookbooks” in the wiki which collate user experience into digestible snippets. It’s important to keep these up to date, make sure users are actively involved beyond the project maintainer, and reach out to plugins for which you provide integrations such that those contributors might also update your respective wiki entries.

Finally, I think it would be great to push forward on these language specific guides in a community maintained organization. I’m happy to organize this. These should, of course, be kept in sync with any cookbooks, standardized/edited for quality to some degree, and should be constructed in collaboration with plugin authors.

Closing

Thanks for listening, happy to discuss what we can do to improve the documentation situation in the neovim ecosystem. Please remember to be kind to the people whose software you depend on, especially keeping in mind that many do not speak the same language that you do, so be cognizant of that when criticizing the quality of documentation.

18 Likes
#2

Agree with everything here, very solid points that for sure need to be taken into consideration more often.

I might hold you to that if I get productive free-time this weekend :slight_smile:

2 Likes
#3

I’m definitely still in Class B, but already on my way to switching to Class A.

I just want to say that I have tried VIm and Neovim atleast 4 times in the past 15 years. Every single time I gave up because I found it difficult to finalize an upgrade - whether I was adding a plugin or customizing my init.vim to specifically adjust the workflow to my liking it always left me unanswered questions and an unstable editor.

This time around I just know to be patient and to dig myself into the documentation and re-read the documentation until it I understand it.

4 Likes
#4

This reflects exactly my feelings about so many of the new plugins. It’s really frustrating to want to try out a plugin and then find that there is no proper documentation, just a README with some code snippets like “if you want to do X then copy-paste this code”. Unless it’s a really trivial plugin that doesn’t need extensive documentaiton, but even for those it would be nice to have the instructions available in-editor.

I also especially agree on the issue of YouTube tutorials. So many of them are just “look at how awesome I am, just copy-paste my code and you will be a wizard as well”, they do not explain the details of what they are doing and they do not point people towards the documentation. And each video is at least ten minutes long even if it could have been half as long, because of the YouTube algorithm. I like TJ’s videos because he actually explains what he is doing. Or the old Vimcasts by Drew Neil; he can fit so much information in just a couple of minutes and he points to the reference documentation.

There are a few things I would like to add:

The issue with documentation contributions

Contributing documentation is a chicken & egg problem: to write documentation I would first need to understand the plugin, but without documentation I would then have to read the source code (which is usually barely commented), and at that point I just give up and write a rant on the internet.

Being aware of the target audience

Documentation authors should be aware of who their target audience is and not repeat information that they can expect readers to know. In particular, I don’t think there is a need to every single time repeat three different ways of installing a plugin. If someone wants to install a plugin I should be able to assume they know how to install a plugin in the first place, and if they don’t they can look it up once and for all. Documenting the installation process should be reserved for plugins that do actually have extra steps or dependencies.

On documentation generators

There are tools which can convert a Markdown file to a Vim help document. I really don’t like those because their output looks hideous when displayed in Vim. It lack all the tasteful manual formatting a human can add to the text. Markdown is a markup language, it does not matter how it is formatted because it is meant to be converted to lower-level formats like HTML. The fact that it is human-readable is just a nice bonus. Vim help documents on the other hand are actually meant to be consumed directly, not converted to another format.

Vim help is not a language

I have heard a number of people say they don’t want to learn a new markup language just for writing plugin documentation, they would rather write in a language they understand and convert from. I think we should emphasize that Vim doc is not a language, it is just plain text with some loose conventions.

Writing documentation is good for the author as well

Another thing I hear often is that programmers don’t like to write documentation, which has always struck me as bizarre. Writing documentation to me is like a meditative process of self-reflection. Often times while I am writing the code I think that a particular idea is really good, but when the time comes to actually explain it I find myself struggling really hard. If it is hard for me to explain, how much harder must it be for someone who does not know the code to understand it? If writing documentation is hard, then that’s a sign that the interface is really not that good.

2 Likes
#5

I agree with basically all of your points, just some notes below.

to write documentation I would first need to understand the plugin, but without documentation I would then have to read the source code (which is usually barely commented)

Yes, I definitely sympathize with this point of view. I as a plugin maintainer have tried actively soliciting feedback on the readme at many points and often it is extremely hard to get usable input without repeatedly pinging people. I think often times this really requires a “hero” (be it the plugin author or a motivated 3rd party to make it happen). I think we should set an expectation on both plugin authors and the community going forward. Lua is bringing a lot of new plugin authors into the fold (I guess by some measures I fall into this group), so part of this is probably inexperience.

In particular, I don’t think there is a need to every single time repeat three different ways of installing a plugin.

To some extent I think it’s time for standardization. As a maintainer, I don’t want to confuse my readers, but I also don’t want to seem like I’m “blessing” certain plugins. At the same time, when something has a large enough mindshare (like packer does currently in the neovim plugin world), it’s probably good for familiarity to just embrace it as readers may be more familiar with it.

A related issue is is the init.vim vs init.lua example. This sounds small, but so many people get confused with lua heredocs. Do we start providing pure lua examples front and center? Not sure. Maybe we should wait for improving the keymap, autocmd, and command interface before we fully embrace lua-first documentation.

If someone wants to install a plugin I should be able to assume they know how to install a plugin in the first place

Soft disagree just from experience, I do think including the packer snippet is useful. Many plugins often draw first time plugin users (lspconfig deals with this), and it doesn’t take up much space in the readme. Maybe if we had a “community guide” on installing plugins we could hyperlink to that would be a good compromise.

I really don’t like [markup generators] because their output looks hideous when displayed in Vim.

This could be improved for sure. I hacked babelfish together in basically a night, and didn’t put much more effort into it. I do agree that a bespoke doc is always better, but in the event that it might grow stale having something auto-generated is preferable (to me). We’re talking about adding some markdown support to :help in core. I think markdown has a lot of favorable properties compared to vimdoc, specifically the ability to inject language highlighting via treesitter which will make reading code snippets much easier.

Vim help is not a language

Yes, I think :help help-writing is surprisingly buried, maybe we should have a more worked example somewhere.

1 Like
#6

I try to at least set an example by documenting my own plugins, just as I am used to great documentation from plugin authors whose plugins I was using. I fear that poor documentation might set off a rotting trend where new people start using poorly documented plugins and then continue the trend with their own plugins.

My problems are twofold: there is nothing about Packer that makes it official, and it’s just noise. Packer my be very popular, but so is also vim-plug. Packer is also quite complex, and for a beginner it might be simpler to just git clone into ~/.local/share/nvim/site/pack/my-plugins, which is actually one official way out of many. As for the noise, if I have twenty plugins that all contain the same boilerplate I start mentally ignoring that section. Then where there is that one plugin that does actually require an extra step I miss it and wonder why the plugin is broken.

Auto-generated from what? The README? We already agree that it is the wrong place for documentation. From a doc/foo.md to a doc/foo.txt? Maybe, but at that point it’s trivial to convert it to Vim help and keep it in that format, something even a contributor could do. The hard part is writing the documentation in the first place.

That would be pretty cool, but couldn’t that be added to Vim help as well by extending the syntax? Something like

Copy-paste this to be as cool as I am:
>vim
    nnoremap kj <esc>
<

Sounds good. Maybe make it its own document and add advice on how to structure good documentation and provide examples? Then we can devote more space and detail than what the current documentation does.

#7

Auto-generated from what? The README? We already agree that it is the wrong place for documentation. From a doc/foo.md to a doc/foo.txt ?

I was thinking a doc/foo.md (or doc/README.md which would get rendered into markdown by default). Since lspconfig didn’t do this (mostly, I already heavily documented things in the readme/wiki), and to avoid claims of hypocrisy, I have merged the following PR which I believe brings lspconfing in line with what I advocated for with this post.

#8

I know I am jumping into a big discussion, but I think this strategy doesn’t work well because it’s in the “wrong direction”.

A sensible documentation generator setup, in my opinion, would be something like this:

  • Developer writes specially-formatted “doc comments” in their Vimscript and Lua source code (+ Fennel docstrings).
  • A doc generator tool collects all of those doc comments into a (snippet of a) Vim help file, like the contents of the api-global help section, which can be stitched together (along with additional explanatory text, examples, etc.) into a help file, like api.txt.
  • A separate tool can generate Markdown or HTML from the Vim help file.

Of course people will sometimes drag their feet on learning the Vim help markup. But I disagree that it’s not a markup language! It clearly is a markup language, with specific markup syntax. But one problem is that there’s no obvious quick reference for it. In addition to the suggestions above regarding help-writing, I think adding a “cheatsheet” section will help people feel more comfortable, knowing that they can quickly look up syntax, instead of having to dig through a detailed help document.

#9

I think that Vim help is similar to GNU Info. Both have some formally defined parts, but the bulk of the text body is rather free-form. Here is no unambiguous grammar that can cover every Vim help file.

Now that I think about it, GNU Info documents are generated from GNU Texinfo documents. Vim already requires running :helptags, so having a standard :helpgen command that generates nicely formatted free-form documentation from a more rigid markup language might be a nice idea. But that brings us back to the original problem of people not wanting to learn a new markup language. The command could support Markdown, but I think Markdown is too crude for documentation. Maybe reStructuredText? It is extensible with custom roles and directives, so we could define a set of Neovim-specific extensions.

Or you know, just use Texinfo and finally admit that we are turning Vim into Emacs :wink:

1 Like
#10

Now that I think about it, reStructuredText really seems like a good fit. It is not as popular as Markdown, but it is common, it has a formal specification, it has a reference implementation (docutils), it is supported by tools like Pandoc, and it gives us all the markup features we need for writing Neovim documentation.

I have written a short mock-up of what a template might look like:

reStructuredText documentation template 
.. default-role:: code


##############
 Example.nvim
##############

.. meta::
   :author-name: John Doe
   :author-email: jdoe@example.com
   :website: https://example.com
   :license: MIT License
   :synopsis: An example plugin
   :depends: 0.6.0
   :date: 2022-02-30

This is an example of how the template of a Neovim plugin documentation could
be written in reStructuredText.

.. We can even have comments which will not show up in the rendered output


.. Auto-generated table of contents with an explicitly set depth
.. contents::
   :depth: 2


Introduction
############

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eligendi non quis
exercitationem culpa nesciunt nihil aut nostrum explicabo reprehenderit optio
amet ab temporibus asperiores quasi cupiditate. Voluptatum ducimus voluptates
voluptas?


Commands
########

The following commands are provided

.. A custom directive which parses one or more Vim script files for
   documentation comments an generates reference documentation
.. vim-commands::
   :file: plugin/example.vim


Functional API
##############

Every function has a Vim script and a Lua equivalent with similar calling
conventions. Consider these two examples:

.. code:: vim

   let my_value = example#basic#foo()

.. code:: lua

   local fe = require 'example.frontend'
   local my_value = fe.foo()

Vim functions
=============

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Qui dicta minus
molestiae vel beatae natus eveniet ratione temporibus aperiam harum alias
officiis assumenda officia quibusdam deleniti eos cupiditate dolore doloribus!

.. vim-functions::
   :file: plugin/example.vim

.. vim-functions::
   :file: autoload/example/basic.vim

.. vim-functions::
   :file: autoload/example/advanced.vim


Lua functions
=============

Ad dolore dignissimos asperiores dicta facere optio quod commodi nam tempore
recusandae. Rerum sed nulla eum vero expedita ex delectus voluptates rem at
neque quos facere sequi unde optio aliquam!

.. lua-module::
   :file: lua/example/frontend

.. lua-module::
   :file: lua/example/backend

And here is what the rendered output would look like:

generated Vim help document 
*example.txt*	An example plugin for Neovim version 0.6+	Last change: 2022-02-30

                                                                *Example.nvim*
Author: John Doe <jdoe@example.com>
License: MIT License
Website: https://example.com


This is an example of how the template of a Neovim plugin documentation could
be written in reStructuredText.


==============================================================================
TABLE OF CONTENTS

1. Introduction .............................................. |example-intro|
2. Commands ............................................... |example-commands|
3. Functional API .............................................. |example-api|
   3.1 Vim functions ....................................... |example-api-vim|
   3.2 Lua functions ....................................... |example-api-lua|


==============================================================================
INTRODUCTION                                                   *example-intro*

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eligendi non quis
exercitationem culpa nesciunt nihil aut nostrum explicabo reprehenderit optio
amet ab temporibus asperiores quasi cupiditate. Voluptatum ducimus voluptates
voluptas?


==============================================================================
COMMANDS                                                    *example-commands*

The following commands are provided


                                                                    *:Example*
:Example {foo} {bar}

    Lorem ipsum dolor sit amet, consectetur adipisicing elit. Eligendi non
    quis exercitationem culpa nesciunt nihil aut nostrum explicabo
    reprehenderit optio amet

==============================================================================
FUNCTIONAL API                                                   *example-api*

Every function has a Vim script and a Lua equivalent with similar calling
conventions. Consider these two examples:
>
    let my_value = example#basic#foo()
<
and
>
    local fe = require 'example.frontend'
    local my_value = fe.foo()
<

------------------------------------------------------------------------------
VIM FUNCTIONS                                                *example-api-vim*

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Qui dicta minus
molestiae vel beatae natus eveniet ratione temporibus aperiam harum alias
officiis assumenda officia quibusdam deleniti eos cupiditate dolore doloribus!

foo({bar}, {baz})                                                        *foo*

	Qui dicta minus molestiae vel beatae natus eveniet ratione temporibus
	aperiam harum alias officiis

herp({derp})                                                            *herp*

	Qui dicta minus molestiae vel beatae natus eveniet ratione temporibus
	aperiam harum alias officiis

------------------------------------------------------------------------------
LUA FUNCTIONS                                                *example-api-lua*

Ad dolore dignissimos asperiores dicta facere optio quod commodi nam tempore
recusandae. Rerum sed nulla eum vero expedita ex delectus voluptates rem at
neque quos facere sequi unde optio aliquam!

... You get the idea


==============================================================================
 vim:tw=78:ts=8:ft=help:norl:

There are still some open questions, such as how Lua functions should be documented; Lua does not have a real module system, so a parser would have to dig through a Lua file and determine which functions are actually exported and under what name. I don’t know how other tools decide this. As for the implementation, first we would need a reStructuredText parser for Lua; there is no such thing apparently, so either it’s a hard task or no one else has thought of it before? Then we would need a parser for Vim script and Lua that can find documentation comments and read function and command signature. Would such a parser be able to catch everything? Even commands which are produced through :execute by gluing together strings?

1 Like
#11

Now that I think about it, reStructuredText really seems like a good fit. It is not as popular as Markdown

I personally prefer commonmark to RST (https://commonmark.org/) which also has wide support and a strict spec, but I can see arguments for both. Markdown is significantly more popular (to the point that sphinx added support for commonmark).

Lua does not have a real module system, so a parser would have to dig through a Lua file and determine which functions are actually exported and under what name. I don’t know how other tools decide this.

You can look at the implementation in the docgen module used for Telescope, which is distributed as part of tree-sitter-lua:

As for the implementation, first we would need a reStructuredText parser for Lua; there is no such thing apparently, so either it’s a hard task or no one else has thought of it before?

I would guess demand, there’s a markdown parser but only one.

#12

CommonMark is still just barebones Markdown, its selling point is that it has a proper unambiguous specification instead of all the wild Markdown implementations that we had before. My main argument in favour of reStructureText (reST) is roles (for inline text) and directives (for block elements); they are sort of like functions in the sense you call them with
some parameters and they act as instructions for the text processing application.

Unlike the various extensions from different Markdown flavours, all roles and directive use the same syntax. It’s just a matter of knowing which roles and directives exist and which arguments they take, the syntax is always the same. We could then augment our processor with support for our Neovim-specific roles and directives for things like splicing in reference documentation parsed from source files.

A middle ground between reST and CommonMark is Markedly Structured Text (MyST). It’s a superset of CommonMark extended with roles and directives. That’s nice for users, but the MyST spec has an escape hatch for embedding reST, which sounds like a real headache for parsing. Every compliant MyST parser would have to also embed a reST parser, and we don’t really gain anything over reST feature-wise.

1 Like
#13

Not sure if this is the place for it, but isn’t it possible to just add configuration tutorials in the Neovim website? Also add user given configurations, with a 5 star rating system. Similar to VS Code’s marketplace.

This way Neovim users can simply download a working configuration that suits them and then learn by adjusting it to their preference. This is not only useful for user class B, but also user class A, since it decreases the chances of reinventing the wheel.

Also, since the rating system is given by the users, a simple graph showing the average review values per month in the past 5 months (like Steam game reviews, for example) could give a strong indication whether the configuration file relies on up-to-date plugins or not.

So as long as class A users provide the configuration files, the docs do not even have to change (although it would still be beneficial for them of course).

#14

This isn’t about documenting “neovim”, we really (at least I don’t) want to encourage people to copy/paste configuration files for neovim, it almost always is correlated with not understanding the underlying plugins/misfiling bug reports to the wrong repos. This is about documentation for plugins.

#15

Yes, I understand that. And I do believe your suggestions are great improvements for the general neovim plugin ecosystem.

But what I am mostly addressing is “onboarding new users”, “accessibility to newcomers” and especially users from class B who much prefer to just get to coding without spending ages trying to configure their coding environment (or Personalized Development Environement - PDE - as TJ de Vries describes it).

My suggestion basically makes class A users quality controllers for the plugins, since they will mostly be the ones uploading configuration files. Users then complain to the configuration file uploader and do not misfile bug reports to wrong repos.

Edit: if the “neovim marketplace” idea is unacceptable, at least adding tutorials in the official Neovim website explaining how to make a configuration file, how to read the plugin docs and how to correctly file issues would be a huge step in easing newcomers from going to “neovim scripters” to “class A users”.

#16

I struggled with this topic myself when writing documentation for neo-tree. After toying around with various converters and generators I came to the conclusion that the best way to write documentation is in the native format. This is both because I want to format specifically for the format I am targeting, and because it takes time (that I don’t have) to learn another syntax/mindset for writing docs. I decided on vim help doc for the complete reference and the README as an advertisement and Quickstart to get the plugin installed.

I also don’t feel that generating end user documentation from my internal API makes sense. It just doesn’t correlate to the functionality that the end users are going to interact with, which emerges from the configuration and not the functions themselves.

One thing that I think would help is if we are consistent in our approach so that new users can learn what to expect quickly. If we all used :help as our primary documentation and made that fact very prominent in the README, maybe we can get everyone on the same page. I know we are not going to get veterans to accept that we are consolidating on the README as the core documentation, so let’s push group B into the habit of looking for the :help file when they have a question.

Existing plugins that have already put all their docs into the README probably aren’t going to re-write them, but if we can get new plugins to follow established guidelines on how to write documentation, then that’s enough to create enough consistency for new users to latch onto. The key is to establish some guidelines on README and help docs which are blessed and promoted by the core neovim developers. Whatever those guidelines are, put them on the front page of neovim.org, post them on reddit repeatedly, have TJ mention them on youtube, etc.

If you are really willing to put some work into this, you could create an example lua plugin as a template for new plugin developers. Create a README in the ideal structure with instructions “Put a short description of your plugin here, 1 - 3 sentences”, “Put your default or recommended mappings here”. Also add the proper folder structure and some basic lua modules to illustrate the structure. Add a docs/my-plugin.txt file with some nice structure and instructions just like the README. If this already exists and I just don’t know about it, then it just needs to be advertised better.

#17

I also want to add that whatever my personal decisions were in the past, such as not using a converter, if you put your weight behind something and really pushed to establish a standard, then I would follow your lead @mjlbach and change my project as needed.

#18

After toying around with various converters and generators

Not to rehash too much from the thread, but I also toyed with converters (including writing one) and came to the conclusion that for now writing vimdoc is the way to go.

I also don’t feel that generating end user documentation from my internal API makes sense.

I think it only makes sense when you expose many lua functions that users are expected to call, like a library such as plenary.

One thing that I think would help is if we are consistent in our approach so that new users can learn what to expect quickly. If we all used :help as our primary documentation and made that fact very prominent in the README, maybe we can get everyone on the same page.

That was basically the goal of this post, but probably need to advertise this better. For what it’s worth lspconfig follows this model of README - vimdoc - wiki pretty well now.

Whatever those guidelines are, put them on the front page of neovim.org, post them on reddit repeatedly, have TJ mention them on youtube, etc. If you are really willing to put some work into this, you could create an example lua plugin as a template for new plugin developers

Perhaps I could convert this post into something more akin to a specification/manual. For reference there are a few things we’ve (mathias at least) have done towards this, such as the example nvim plugin which needs to get fleshed out and advertised.

But yeah, turning this post into a subcomponent of a plugin guide is on my to-dos.

#19

If that repo was fleshed out with all of your ideas it would be awesome, provided people actually know about it. I think these are all great ideas and I hope you (or someone else) follows through on them. I just checked and lspconfig is really well done project and had someone said to me “use lspconfig as an example” when I started it would have been very helpful. It’s a shame that I never read the README before now, I think I actually got all of my config for that from reddit posts!

Not to change the subject, but I’d like to point out that there is always a lot of discussion on the subject of maturity, discover-ability, and ease of use of the plugin ecosystem. This post on improving documentation is attempting to fix one aspect of that, but if we truly want to make neovim more accessible to “User Class B”, I think a more holistic approach of creating a centralized database of plugins with a gui plugin manager where you can search, install, and configure plugins like VS C*** is the ultimate solution. That is what “User Class B” really wants.

An alternative to starting a big complicated project like that is to just point new users to LunarVim, which is probably what most VS C*** users would choose if they knew it existed.

#20

but if we truly want to make neovim more accessible to “User Class B”, I think a more holistic approach of creating a centralized database of plugins with a gui plugin manager where you can search, install, and configure plugins like VS C*** is the ultimate solution.

That’s a big if :slight_smile:

I don’t think such an initiative would come from core, because I don’t think any of us are the kind of users that would benefit from this, and also recruiting user class B explicitly does not make sense because we are not a company and there is no direct motivation to expand the size of the userbase. We already have a strong donation base, so I don’t think that seeing this as an additional funding source is strong enough motivation. (this is me just wildly speculating on behalf of myself alone)

I’m happy to extract some of the practices from this post and lspconfig into the example lua project with a writeup, it’s just towards the back of the queue.