mrcjkb
commented
3 months ago 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/
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:
pros of rep:
:helpWe 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.