Useless Documentation due to Keybindings Overwriting (Vanilla Install)


#1

Hello everyone,

I am new to Atom and wanted to go through the documentation before I start. However, I find that a lot of the shortcuts described in the documentation don’t work. When I looked at the keybindings in the settings I found that they are being over-written by shortcuts in other packages. Mind you, I have a vanilla install of the editor and no custom packages installed. (The most recent one that comes to mind is ctrl+t which is used by Fuzzy Finder: toggle-file-finder. But there are many… like most of the moving and selection related shortcuts that would contribute a lot to productivity once the user gets the hang of them.) However, after going through a couple of chapters of documentation I found only a couple of shortcuts work as described and it became increasingly difficult to remember which worked and which didn’t. At this point reading any further was just useless since it was causing more trouble to test each shortcut if it worked or not. The point being that this sort of issues cause bad learning experience and greatly slow down adoption. I would suggest the following to remedy the situation (maybe they are not the best, but probably would have helped me).

  • Make sure that the vanilla install has all the keybindings working correctly as described in the documentation on any specific platform
  • Include a reset functionality that resets the keybindings to vanilla if the user feels like going back to the original (regardless of the packages installed - this should be easy - if package specific keybindings are needed again the user can manually set them since the user installed that package since it’s not part of vanilla).

#2

The documentation, like everything else in Atom, is maintained by the community. What you can do to be helpful is when you find something wrong in the documentation is you can file an Issue on the documentation repository or, even better, submit a Pull Request with a fix.

Also, a better approach to keybindings in the documentation was discussed here:

And filed as an Issue here:


#3

Sounds good. I will follow up on the doc repository. However, is the goal to match the documentation to the product or is there an expected (minimal) key-bindings map which should be after the install and needs to be adhered to ?


#4

I don’t see the two goals you mention as mutually exclusive. The documentation can match the product and the product can have sensible defaults. Everyone wins :grinning: