README.md / documentation (slight) revamp

[teto]

I would like to help with the documentation as I go through the discovery phase (it's harder later, once you are used to the plugin) but I would like some feedback on how to do that in a way that pleases all contributors.

I've dumped a bunch of stuff on the wiki as I go (sometimes ugly):
https://github.com/nvim-neorocks/rocks.nvim/wiki/Plugin-support
https://github.com/nvim-neorocks/rocks.nvim/wiki/Troubleshooting
https://github.com/nvim-neorocks/rocks.nvim/wiki/Home

and would like to avoid redundancy (though) not critical.

I guess my main question is Wiki vs repo:

pros of wiki:

• easy to edit, especially as the plugin evolves

pros of rep:

• we can review edits but slow
• can be included in the :help

We can have distinctions per topic (troubleshooting should live in repo) while the guides to upload a plugin remains on the wiki since less critical.

We can also do as neovim did, start iterating on the wiki and once it has stabilized move some pieces to the repo.

I will prepare a README PR that can serve as a starting point for discussion.

[mrcjkb]

We can also do as neovim did, start iterating on the wiki and once it has stabilized move some pieces to the repo.

I think this is a great idea.

In general, I think the readme will be the entry point for most users. It should have a concise introduction and installation instruction + a tutorial for the basic usage.

In the long term, more detailed documentation regarding plugin usage should go in the luaCATS/generated vimdoc.

Information like how to get plugins on luarocks can live in the wiki.

This is quite a long read, but I really like the approach: https://diataxis.fr/