Documentation

[kylechui]

How does everybody actually use the help docs? It does feel like at this point I might end up managing two separate copies of similar/the same documentation (help docs and wiki), and I'm unaware of what solutions exist for this problem. Should I be doing everything in the help docs as opposed to the wiki? I personally feel that the wiki is able to better organize/contain a larger amount of information, but I also think that being able to get help on stuff without leaving Neovim is essential.

My current thought process is that perhaps the wiki would contain more "user-friendly" content:

• Quickstart configurations to make the plugin "feel" more like vim-surround/vim-sandwich/mini.surround
• Feature overview: Brief showcase of the various options that people might want to use, how to set them up, the "reasoning" for how stuff works
  • In particular, custom adds, custom deletes/changes
  • Lookahead/lookbehind (or jumping, naming is hard)

Then that would leave the help docs to contain "more direct documentation":

• Probably add a note at the beginning that the wiki is where you learn about new things, and the help docs is mainly for reference
• Documentation on the configuration functions available to the end user, e.g. config.get_input(), config.get_selection(), etc.
  • What arguments they take, maybe some examples here and there, but not what the purpose of such functions are(?)
• Less about how stuff works, mainly showing syntax and examples as reference so you can configure nvim-surround without leaving Neovim

CC: @akinsho @NoahTheDuke @andrewferrier @jonatan-branting @smjonas @melkster I'd like to get some feedback on the prior ideas; or just leave a 👍 or 👎, thanks!

[NoahTheDuke]

As I see it, :help docs should exist for everything that might be useful while using or configuring the plugin: defaults, ways to change keys, examples of the various config options, etc. The wiki is best for "stuff that is cool but ancillary to direct usage", such as "cool custom configs" or "ways to bend or break the plugin" or "really deep dives into how to build something".

[smjonas]

I think that using the Wiki for showcasing custom surrounds is better. This makes the help docs less verbose and you could also include images / videos if you want to for certain examples.

What arguments they take, maybe some examples here and there, but not what the purpose of such functions are(?)

Imo, the help docs should be "complete" in a sense that a user does not need to jump to the Wiki to find out the purpose of a particular API function. For me, that also includes an explanation (at least a short one). The Wiki does not have to go into too much detail and you could instead refer users to the helpdocs.

Also how are you currently creating the Vim-docs? You could use tools such as https://github.com/kdheepak/panvimdoc or https://github.com/numToStr/lemmy-help to generate the vimdocs from Markdown or emmylua annotations so it's less work for you :)

[kylechui]

Also how are you currently creating the Vim-docs?

Manually 😅

I'll look into those tools for streamlining the process. I think as of right now I don't mind writing the docs by hand, as long as I only need to do it in one spot (I'll need to anyways, regardless of how things are done). I think this sort of demarcation of the help docs as "the main, complete source of info" and the wiki as "more complex examples/non-essential information" sounds good to me. I just find that sometimes it's a bit awkward to format the help docs to be within 78-80 characters wide. I'll take a look at other projects with longer help docs for inspiration.