{"action":"created","issue":{"url":"https://api.github.com/repos/syl20bnr/spacemacs/issues/772","labels_url":"https://api.github.com/repos/syl20bnr/spacemacs/issues/772/labels{/name}","comments_url":"https://api.github.com/repos/syl20bnr/spacemacs/issues/772/comments","events_url":"https://api.github.com/repos/syl20bnr/spacemacs/issues/772/events","html_url":"https://github.com/syl20bnr/spacemacs/issues/772","id":60186954,"number":772,"title":"RFC: Improve Spacemacs experience for new users","user":{"login":"chrisbarrett","id":836504,"avatar_url":"https://avatars.githubusercontent.com/u/836504?v=3","gravatar_id":"","url":"https://api.github.com/users/chrisbarrett","html_url":"https://github.com/chrisbarrett","followers_url":"https://api.github.com/users/chrisbarrett/followers","following_url":"https://api.github.com/users/chrisbarrett/following{/other_user}","gists_url":"https://api.github.com/users/chrisbarrett/gists{/gist_id}","starred_url":"https://api.github.com/users/chrisbarrett/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/chrisbarrett/subscriptions","organizations_url":"https://api.github.com/users/chrisbarrett/orgs","repos_url":"https://api.github.com/users/chrisbarrett/repos","events_url":"https://api.github.com/users/chrisbarrett/events{/privacy}","received_events_url":"https://api.github.com/users/chrisbarrett/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/syl20bnr/spacemacs/labels/~%20RFC%20~","name":"~ RFC ~","color":"bfe5bf"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":24,"created_at":"2015-03-07T02:55:43Z","updated_at":"2015-04-19T10:57:34Z","closed_at":null,"body":"This is a dump of my experience coaching vim users switching to Spacemacs over the past 2 months. I want to see what improvements people would approve of before I start logging individual issues and submitting PRs.\r\n\r\n# tl;dr\r\n- We should automate more parts of the Spacemacs setup procedure\r\n- We should also consider adding an in-Emacs tutorial on setting up everything else\r\n- We need to think about ways to help users customise their keybindings\r\n- We need a better documentation system than GitHub (e.g. [ReadTheDocs][])\r\n \r\n# Background\r\nI've been hands-on, helping 4 vimmers at work switch to Spacemacs. Three of them have stuck with it and think it's awesome, and the other gave me valuable feedback about what turned them off.\r\n\r\nFrom my experience coaching them and based on their feedback, I can make some general observations about their Spacemacs experience. I'll call them 'users' for ease of writing, but I don't want to imply that I'm speaking for all users. :)\r\n\r\n# Issues\r\n1. Users want to jump right in, so they read the Readme.md but not the documentation\r\n2. Users get stuck the moment they need to configure anything that's not in `~/.spacemacs`. They don't know how to manage their own config layers.\r\n3. There are too many ways to configure key bindings, and it's not always clear which to use.\r\n4. Vim users expect to be able to bind whatever they want to `,` as their leader key, and the way Spacemacs hijacks comma for `SPC-m` is frustrating\r\n5. Vim users expect a single keybinding for finding files pretty much anywhere.\r\n\r\n## Issue 1: Documentation\r\n\r\nAs we all know, the documentation needs to be improved. GitHub does not provide a good experience for reading documentation, especially because readmes get scattered around the different layers and neglected. \r\n\r\nWe should consider putting our documentation on [ReadTheDocs][]. Flycheck does this and it rocks. We should also make updating the docs standard practice following feature PRs. \r\n\r\n## Issue 2: Configuration\r\n\r\n### .spacemacs\r\nThe `~/.spacemacs` config file thing is working fine, but users consistently get stuck when they create new config layers and forget to update their `.spacemacs` to wire them up.\r\n\r\nWe should consider automatically loading any config layers in `.emacs.d/private`.\r\n\r\nConfiguring spacemacs requires elisp, and there are surprisingly few good tutorials out there on elisp. I might write our own one for inclusion in the documentation.\r\n\r\n### config layers\r\n\r\nYou really need to read the documentation to understand how to use config layers, and we've established that users don't read the documentation. ;)\r\n\r\nI think we should *always* create a `config.el` and `keybindings.el` when interactively creating a new layer. We should also improve the explanatory comments in the templates for those files -- I'm happy to submit a PR on that one.\r\n\r\n## Issue 3: Customising Keybindings\r\n\r\nConfiguring keybindings right now is hard. Any time users want to bind something, they have to know which of the following to use:\r\n- `define-key`\r\n- `global-set-key`\r\n- `evil-global-set-key`\r\n- `evil-define-key`\r\n- `bind-key`\r\n\r\nThese all bind keys in different situations, so if a user picks the wrong one things will work *some of the time*, which is worse than things not working at all!\r\n\r\nWe can probably write an interactive key binding utility that reads a key sequence, asks which states and modes to bind it in, and then automatically write the correct setting to a keybindings file. Otherwise, we need a flowchart in the documentation. :(\r\n\r\n## Issue 4: Customising the Evil Leader\r\n\r\nVimmers expect to be able to bind their stuff to `,` (comma). The current practice of putting ever-changing mode-specific bindings there is not helpful to them, because their own bindings get clobbered. I don't believe mapping `,` to `SPC m` pays its way, given that this is what I see in scala-mode:\r\n\r\n![screen shot 2015-03-07 at 3 30 36 pm](https://cloud.githubusercontent.com/assets/836504/6539678/304861e6-c4df-11e4-9b86-2adb18efc85c.png)\r\n\r\nThat's utterly bewildering, and of course when those mapping were introduced they clobbered my existing bindings which I had set up and *did have meaningful names*. \r\n\r\nI suggest we revert the mapping from `,` to `SPC m` so that users can safely customise their leader again.\r\n\r\n## Issue 5: File Navigation and Helm\r\n\r\nThe first thing experienced Vim users ask me is if we have [Control-P][] or [Command-T][] equivalents in Emacs. I set them up with `helm-for-files` bound to `C-SPC` and they're happy. This puts buffer killing, switching, and file search in one place, and cleanly avoids all the separate emacs-y commands for doing this stuff. The users I've coached unanimously love helm.\r\n\r\nI believe `C-SPC` is a good binding, because it's normally used for `set-mark-command` which we never use in evil. If set with bind-key, it works globally, no matter what buffer or state they're in, so they feel confident that they can move around in Emacs without getting lost.\r\n\r\nI propose we bind `C-SPC` to `helm-for-files` in the base distribution of Spacemacs.\r\n\r\n# Conclusions\r\n\r\nI'm hoping none of the above is too contentious. ;) I'm interested in feedback from @syl20bnr, as well as @trishume, @bjarkevad and other regular contributors on these points, because your experiences may be very different!\r\n\r\n[ReadTheDocs]: https://read-the-docs.readthedocs.org/en/latest/index.html\r\n[Control-P]: https://github.com/kien/ctrlp.vim\r\n[Command-T]: https://github.com/wincent/Command-T"},"comment":{"url":"https://api.github.com/repos/syl20bnr/spacemacs/issues/comments/94264368","html_url":"https://github.com/syl20bnr/spacemacs/issues/772#issuecomment-94264368","issue_url":"https://api.github.com/repos/syl20bnr/spacemacs/issues/772","id":94264368,"user":{"login":"edwintorok","id":721894,"avatar_url":"https://avatars.githubusercontent.com/u/721894?v=3","gravatar_id":"","url":"https://api.github.com/users/edwintorok","html_url":"https://github.com/edwintorok","followers_url":"https://api.github.com/users/edwintorok/followers","following_url":"https://api.github.com/users/edwintorok/following{/other_user}","gists_url":"https://api.github.com/users/edwintorok/gists{/gist_id}","starred_url":"https://api.github.com/users/edwintorok/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edwintorok/subscriptions","organizations_url":"https://api.github.com/users/edwintorok/orgs","repos_url":"https://api.github.com/users/edwintorok/repos","events_url":"https://api.github.com/users/edwintorok/events{/privacy}","received_events_url":"https://api.github.com/users/edwintorok/received_events","type":"User","site_admin":false},"created_at":"2015-04-19T10:57:34Z","updated_at":"2015-04-19T10:57:34Z","body":"regarding `CtrlP` replacement, I found `helm-projectile` quite nice, after I modified it to show only files tracked by git:\r\n```\r\n  (setq projectile-enable-caching nil)\r\n ;;; Show only files tracked by git in helm-projectile\r\n  (setq projectile-git-command \"git ls-files -zc --exclude-standard\")\r\n  (bind-key (kbd \"C-SPC\") 'helm-projectile)\r\n```\r\n\r\nHowever this can be quite slow when not inside a project, in which case maybe a fallback to your suggestion of `helm-for-files` would be nicer.\r\n\r\nThis is similar to how I use CtrlP in vim, and its a lot faster (and cleaner) than using find on large projects:\r\n```\r\nlet g:ctrlp_by_filename = 1\r\nlet g:ctrlp_match_func = { 'match': 'pymatcher#PyMatch' }\r\nlet g:ctrlp_user_command = {\r\n\\ 'types': {\r\n\\ 1: ['.git', 'git --git-dir=%s/.git ls-files --cached --exclude-standard'],\r\n\\ 2: ['.hg', 'hg --cwd %s locate -I .'],\r\n\\ },\r\n\\ 'fallback': 'find %s -type f'\r\n\\ }\r\n```"}}