you got the README wrong

[klosworks]

One of the necessary purposes of the README is to explain what the software does so that people can estimate if it's worth trying it out.

I would expect at least a short paragraph with an explanation. This would still be quite inadequate in comparison with other vim plugins which actually do a detailed comparison with in-built vim features, with other plugins and even paste screenshots and gifs that present the features. Short paragraph would be inadequate but you don't even have that, you have nothing, to the point that I wouldn't try your plugin (unless someone recommends it strongly).

What you have now:

• "Comment functions so powerful—no comment necessary." - this is wrong and unhelpful.
• The first paragraph of the Usage section is "Please see the vim help system for full documentation of all options: :help nerdcommenter". This doesn't help because I can't do ":help nerdcommenter" before I install, and I won't install before I know what the plugin does.
• The first piece of information is in the "Default mappings", but it's incomplete, indirect and doesn't explain why I would be faster using your plugin rather than pure vim or another plugin. Also, some people (me included) are lost by this point. I'm only mentioning it because I saw the other PR about the README where you pointed that section out.

I know you argued about a similar thing in a PR in the past, but I don't think you understood the main point.
Look at how other vim plugins do this, for example YouCompleteMe
Seriously I think you are loosing like 75% of people who land on nerdcommenter github page.

[alerque]

This has been mentioned before (see #388) but to my knowledge nobody has ever contributed anything in a PR. I would be happy to review a PR that actually contributed towards fixing this.

[klosworks]

I did a tiny little bit by contributing my explanation above. I know that in a sense it isn't a complete contribution but that's the extent of a contribution I'm willing to make to a project that I don't use due to not knowing what it does.

My issue sounds a bit dry and maybe even rude, so you may be wondering about my motivation. I'm basically annoyed with the general state of open source software and I'm trying to promote a shift to a more user-focused approach to software design.

[alerque]

I'm trying to promote a shift [...]

You're doing it wrong. In the commercial world some companies might be motivated by complaints like this and take the chance to invest a little more in trying to win over new customers. I the open source world whining at projects that they are "doing it wrong" will typically be badly received. I'm not even the original author here and I don't have any particular interest in convincing more people to use the plugin. Why would I invest a bunch of my time trying to support more of the kind of users that don't even know what "commenting" is in a text editor and need to be hand held?

Of course that's not quite right — project adoption does have advantages for everybody, but a lot of this centers around attracting more contributors.

If you want to campaign for OSS projects to improve on this front you need to change your tone and think about what motivates them. Think about what they've contributed so far vs. what they have gained or stand to gain. Write with those things in mind or you're just going to get shut out. Also think about what issue tracker are for from the perspective of project maintainers.

[klosworks]

You're doing it wrong.

I'm not sure about the best way to approach this problem yet. Clearly I'm not having luck trying to convince yourself.

In the commercial world some companies might be motivated by complaints like this and take the chance to invest a little more in trying to win over new customers.

Or, everyone (commercial or not) could be more proactive and make a documentation that says what the software does. A lot of people already do this.

Why would I invest a bunch of my time trying to support more of the kind of users that don't even know what "commenting" is in a text editor and need to be hand held?

Now you are implying untrue things about me and other users. The issue is not about knowing what commenting does. Everybody knows it. The issue is knowing why is your plugin better than native vim or other plugins. For example there is block insertion in native vim that I use, which works well enough in my case.

I the open source world whining at projects that they are "doing it wrong" will typically be badly received.

I'm just trying to point out what's missing. I'm not sure that it will be badly received by everyone. By the way, some things can be said nicely, and some just can't. There's no nice way to say that I think you are loosing 75% of potential users. If you are saying that it's counterproductive to point that out due to psychological reasons, I agree to some extent. Again, I'm not sure how to approach this problem yet.

I'm not even the original author here and I don't have any particular interest in convincing more people to use the plugin.

Then you argue about an issue that doesn't interest you, right?

If you want to campaign for OSS projects to improve on this front you need to change your tone and think about what motivates them. Think about what they've contributed so far vs. what they have gained or stand to gain. Write with those things in mind or you're just going to get shut out. Also think about what issue tracker are for from the perspective of project maintainers.

I tried to point out all the details and how they are not contributing to understanding of the software purpose, but I'm not understood, so let me just put it more bluntly: no one is going to write your documentation for you. It's 10x more work to a new contributor compared to you. Of course you are free to work (or not work) on what you want, but then the problem I have is that a ton of software is produced that isn't well documented, and it has consequences, like the relatively small vim adoption.

[TamaMcGlinn]

@klosworks you are right on all points. Nerdcommenter also does some bizarre things with mappings, and does not support motions; I recommend switching to tcomment_vim as a better alternative. It is also properly documented.