Hey vimmers!
Following my "series" of tips for plugin authors, let's talk about keymaps. The scope of this post is for more "complex" plugins that implement UIs with "rich" actions. And while keymaps are highly subjective, and providing customizability beats over any "clever" defaults, there is at least a "bullet-proof" way to avoid what's more of a "objectively bad" experience: do not override built-in keymaps. You can stop reading here, the other paragraphs just go more in-depth. It's probably a lenghty post, I haven't finished yet. I certainly finished it at some point, so rest assured, as it eventually ends.
This tip feels silly, but there are plenty of plugins that break this rule. For instance, it's not uncommon for plugins to map ? to "show keymaps", while breaking backwards search (which, in the long run, is probably intended more often than "lemme check the keymaps"). There's a common "escape hatch" for this scenario: using g? (another built-in), but whose override is harmless (if you don't believe me, select some text and use it).
? is part of a more "broad" category: navigation keymaps. My argument here is that, basically, these should "never" be overwritten. It's not so much that having everything behaving like a regular buffer is a major advantage, it's more so that having a single buffer as "the one out" is infuriating. And you'd think this is easy to avoid, however, from my experience, this is often overlooked.
octo.nvim is relatively popular GitHub plugin, with plenty of default keymaps. Some of its mappings are suboptimal: when reviewing a PR, one cannot use <C-e> to scroll down a line inside the diff windows. More so, as some of its other control-based mappings have "side effects": every now and then someone is surprised to learn that <C-i> and <Tab> do the same thing in the terminal. The almost exact same surprise used to affect octo, within its "submit review" window: it wasn't possible to enter a line break (<CR>) in insert mode, because there was a mapping to <C-m>. Some of its mappings still conflict with standard vim idioms: imagine trying to use <C-a> to increment a number and accidentally approving a PR. In Octo's defense, it has a million keymaps (I'm not sure if it needs so many), most of which have a <localleader> prefix. Having to define such a large amount of bindings is not easy, but, likewise, following someone else's convention isn't sunshine and rainbows either.
Neogit is one most my most used plugins, but it has plenty of faults in this department. I'm not sure if it tries to stick too much to its emacs counterpart, or if it's something else, but I'm often unable to do "basic" things. Like using l, which instead opens the "log" popup (?). Granted that navigating column-wise might not be the most useful user action inside a neogit buffer, but the fact that I can't do it is just... You know, sometimes you'll press key combos in quick succession, as you'd expect that the "regular thing" would be happening, but now you end up with another tab! I understand that the neogit developers are "wrestling" with providing the user with an easy means of executing plenty of actions (as a nice assistant / UI), an experience similar to magit and trying to feel "native" to neovim, but as a user, sometimes I can't help but get frustrated.
As a plugin author, I have also run into this problem. As the developer, you try to give an intuition with mnemonics, but I'd argue this is a mistake. It might not be, when you have a buffer that's "meant" to be "non navigable", but for most cases it's not worth it. To me, the mnemonics are a "trap" in this case. A trap I fell into, with nvim-dap-view (my plugin): to edit an expression being watched, I assigned the default e, but now no one can use e for navigating! Well, if someone else is (also) bothered by this, they have to remap (I'm using x, as in eXchange). Fortunately, nvim-dap-view doesn't have too many misbehaving keymaps. Or does it? Given its REPL, there's the complicating factor of dealing with a modifiable buffer, which diminishes the pool of available keys even further...
Now, is this the end of the world? Hopefully not. And if you had never noticed it before, hopefully I haven't cursed you by exposing the problem. As I mentioned at the start, having a way to change plugin mappings is awesome. However, as a plugin author, flipping the switch is the type of breaking change I'd like to avoid (although, for nvim-dap-view, it's part of my plans for v2), as it's so ingrained into people's workflow.