search

kylechui / nvim-surround

Add/change/delete surrounding delimiter pairs with ease. Written with :heart: in Lua.
MIT License
3.18k stars 62 forks source link

Provide some simple examples / instructions of how to use in the README #57

Closed andrewferrier closed 2 years ago

andrewferrier commented 2 years ago

Checklist

Describe the solution you'd like I guess one of the things that would be great is to attract more folks to nvim-surround who aren't necessarily users of a surround plugin already.

I know that you have a demo video, but many folks (like me) really don't like watching videos (and minor bit of feedback - I think your video is a little fast to follow it on the first run through anyway). Also, I know you have comprehensive help in :h nvim-surround - which is great.

But looking at the README, the one thing I realized it was lacking is some introductory explanation of how to use the plugin. It jumps straight to configuration, but doesn't talk about some simple default usage, e.g. daq or cr{[. At the least, it would probably be helpful to have some examples, with "before" and "after" text, even if the README isn't a comprehensive reference.

What do you think?

andrewferrier commented 2 years ago

(For what it's worth, from what I've seen, the evolving convention seems to be that the README is for getting started/"selling" your plugin, and the help is for reference information).

andrewferrier commented 2 years ago

I just found out that this point is more than theoretical: https://github.com/kylechui/nvim-surround/discussions/51#discussioncomment-3131542 ;) I think this is precisely the kind of content that would be great to have in the README. You've already written it after all!

kylechui commented 2 years ago

(For what it's worth, from what I've seen, the evolving convention seems to be that the README is for getting started/"selling" your plugin, and the help is for reference information).

Yeah I initially thought that most everybody that would even find this project would have already been using a surround plugin, but I'll add a Usage section to the README now. The original goal was to "trim the fluff" and keep the README as short as possible, thereby not wasting the user's time

andrewferrier commented 2 years ago

(For what it's worth, from what I've seen, the evolving convention seems to be that the README is for getting started/"selling" your plugin, and the help is for reference information).

Yeah I initially thought that most everybody that would even find this project would have already been using a surround plugin, but I'll add a Usage section to the README now. The original goal was to "trim the fluff" and keep the README as short as possible, thereby not wasting the user's time

Yeah, agreed, and I don't think it needs to be comprehensive (you could redirect to help for that); but a short set of examples I think would be helpful at a minimum.

kylechui commented 2 years ago

@andrewferrier Forgot I was on main... oops. Good news is I've written up short blurbs about add/delete/change, take a look and let me know what you think!

Edit: Probably will need to transition away from using the term "insert" for "inserting surrounds", as per #58

andrewferrier commented 2 years ago

Looks perfect!