nvim-surround
nvim-surround copied to clipboard
kylechui
Help me improve documentation!
Note: To respect your time, I will continuously update this top-level comment with information, as new ideas get discussed in the comments.
This project needs a massive documentation overhaul, from the way in which new users are introduced to the project, to having a good way for users to "discover" new features, to being able to use those features in a meaningful way to customize this plugin to their tastes. I think that the overall organizational structure will be as follows:
- README: Contains basic information about the project, tries to get people engaged/interested (GIF/Video, basic list of "big" features, redirect to wiki/help docs where necessary)
- Wiki: Contains more detailed information about the user experience of the project. In essence, enough information to be able to use the project:
- Introduction to surround philosophy (and how it's an extension of Vim's objects)
- Transparent comparisons with other surround plugins, where our shortcomings and strengths are
- Feature discovery: How to surround using HTML-style tags, how to write "functional surrounds", how jumping works, etc.
- Examples, examples, examples! See #53
- Help docs: Contains more technical, granular information that isn't necessarily in the Wiki; should probably be the most "information dense" of the three, getting straight to the point and defining things more "rigorously"
Work that is going to be done on my end:
- ~~Write a CONTRIBUTING.md file for this project~~
- ~~Create a "Breaking Changes" issue that notifies subscribers of what's broken~~
- Add a "For Developers" section to the wiki that explains the overall codebase organization/structure, to hopefully "lessen the barrier of entry" for submitting PRs for basic bug fixes/feature enhancements
Agreed, a nice option might be to have a 'is this feature in surround, sandwich, nvim-surround?' table. It's transparent, easy to read, keeps you honest about plugging feature gaps (where you think they should be plugged), etc.
See https://github.com/lewis6991/gitsigns.nvim#comparison-with-vim-gitgutter for example/inspiration.
Probably worth including mini.surround as well, even though personally I'm not a fan of the packaging of the mini plugins, they are a valid competitor and I've noticed them mentioned on Reddit a few times.
Another thing I would like to add is code blocks to let users just copy/paste "default" configs for setting things up sandwich-style, which I'll need help for since I've never used sandwich
Probably worth including mini.surround as well, even though personally I'm not a fan of the packaging of the mini plugins, they are a valid competitor and I've noticed them mentioned on Reddit a few times.
I'll talk to the dev about it when I actually start writing (oh no), and hopefully they can help clarify any misconceptions I have about it. But yes, I think mini.surround is a great plugin that deserves to be mentioned as well
Sure, I think it's actually pretty simple. I used sandwich bindings for nvim-surround for a few days since I was used to them (trying to wean myself off them now):
require("nvim-surround").setup({
keymaps = {
insert = "sa",
delete = "sd",
change = "sr",
},
})
That's the basics. This doesn't account for the text objects, which I never used and which you don't have support for yet I think (is this issue #52)?
#52 is different, as it is referring to TS-defined text objects like functions, if statements, etc. that nvim-surround can just hook into without the user needing to go back and redefine a bunch of buffer-local maps
I didn't realize that so many people use/depend on using HTML-style tags; they potentially deserve their own page on the wiki, since people seem to be confused by it (see #70 and #71).
I've started basic work on the wiki, and have modeled it to have a similar feel to telescope's wiki, but I'm unsure how to allow other people to contribute to it.
CC: @benfrain In case this is something you'd like to figure out/help with documenting?
@kylechui wiki looks good so far. I guess it's worth thinking about - just in terms of maintainence - what you want the wiki to cover, vs. the docs. You don't want to create too much work for yourself - worth having redirects where it makes sense to do so. Obviously there will some overlap, but my assumption is that the wiki might be more about extensibility / customizations etc.
I think my goal will be to have the docs have the "hard, technical information", while the wiki is more to learn about the existence of certain things/stuff not exactly part of the plugin, e.g. converting from other plugins and comparisons.
@andrewferrier I've updated the top-level comment with a more concrete notion of what I think the various documents should include; I'd appreciate any thoughts or insight you might have. I agree that utilizing redirects would lessen my workload, but I also don't want the user to have to guess where specific kinds of information are---hopefully the structure I've outlined will strike a good balance between the two.
I've started some very basic work on a quickstart page for people migrating from other plugins, but I'm very unknowledgeable about anything other than vim-surround (and even then...). I'll also start work on a "feature showcase" of sorts later as well.
A new version of the help docs is underway in this commit, to be more "conventional" and comprehensive, so users don't have leave Neovim to learn how to use/configure the plugin.
I think one of the most important things to be working on at this point is the documentation. However, I'm not great at writing docs and the plugin is somewhat hard to configure (for the sake of customizability), so I would like feedback on how I can improve my documentation writing skills. Should I include a new section that's just examples? I've also been adding more of the surrounds to #53 to provide more examples, but I don't know if people have been checking it
Suggestion: create some issues/bugs where you know the docs are lacking and tag them 'docs' or similar. Some of us may even be willing to contribute some pull requests, so if you can track what you want doing, we might be able to help...
@andrewferrier I think I'll close this issue for now and open new ones as I feel more specific needs arise. Thanks for the suggestion!