More explicit documentation and UI suggestions

[Andre0991]

Hi

I have been trying to use Ivy in Spacemacs and I must say, I quite like its interface. Good work 👍

I'll list some questions and suggestions:

• Can you point out explicitly where the documentation is in the README? It took me a while to discover the wiki. Probably many users will find it fast but I think it's good the mention it in the README, many projects do this.
• I think it would be great if the ivy buffer had some information on how to get help. helm, for example, displays some basic keybindings - C-c ?, in particular, is crucial. I think using something like that would be great for discoverability. I'm not sure how to display this elegantly. Perhaps like which-key, with a discrete colour:

I think that would be nice to have something like C-bla for help instead of the number of candidates.

• I think it'd be good also to have an indication that you are using Ivy. In Spacemacs gitter chat, sometimes we say something like "you should do this or that in Helm", and the person asks what Helm is, then we can say "Use SPC SPC. Do you see 'Helm blabla' in the bottom?".

Some UI issues with the interface that shows up after pressing C-o

• I don't understand what Yes, No, Maybe and Action mean.
• done is not intuitive name for me. I thought it would exit the Ivy session
• oops is what actually does that - quit (q) would be better in my opinion.
• go also doesn't really convey what it does, IMO. I would prefer "Action", "Execute action" or something like that.

Well, that's it. I hope my suggestions are useful to you. And thanks for creating Ivy, it's great.

[abo-abo]

think it would be great if the ivy buffer had some information on how to get help. helm, for example, displays some basic keybindings - C-c ?, in particular, is crucial.

Ivy does it in an Emacs-standard way - press C-h m or <f1> m while in the minibuffer to see the bindings.

I think it'd be good also to have an indication that you are using Ivy

ivy-mode has an indicator by default. The spacemacs layer suppresses this indicator. See if you can customize the layer.

I don't understand what Yes, No, Maybe and Action mean.

They're just column descriptors meant to bring a bit more structure. The bindings under "Yes" column do stuff, while the bindings in the "No" column cancel stuff.

follow mode - For even more gain, suppose you want to execute the action for several items. You can do so with e.g. C-n C-M-m C-n C-n C-M-m - this will forward a match, execute action, forward two matches and execute action. However, it’s shorter to do this with C-o gjjg.
basically the same as gj but without g

What you describe is true, don't see the point though.

key to get back from C-o - it's backspace, can you provide visual clue

Backspace does the same thing as o does. And C-o is a toggle.

[Andre0991]

Ivy does it in an Emacs-standard way - press C-h m or m while in the minibuffer to see the bindings.

Yes, I know, I used that. I prefer UIs that make things more discoverable, but I understand your point. Consider the Spacemacs case. Let's say that Ivy is the default completion framework (not the case now). If there was a visual clue about C-o or all commands, people would be able to learn about them and use them from day one.

ivy-mode has an indicator by default. The spacemacs layer suppresses this indicator. See if you can customize the layer.

Ops, sorry, I didn't know that. Sure, I'll discuss that there.

They're just column descriptors meant to bring a bit more structure. The bindings under "Yes" column do stuff, while the bindings in the "No" column cancel stuff.

OK, I understand now. But it's hard to tell this from the words Yes and No. And maybe doesn't help too.

What you describe is true, don't see the point though.

Never mind, I was writing this issue and accidentally opened it before writing all the text. I updated it, by the way. That was just an annotation.

key to get back from C-o - it's backspace, can you provide visual clue

Sorry, same thing, this was just an annotation.

Thanks for your answer. Please read the updated post.

[Andre0991]

I updated my answer a bit too. Please read it on GitHub if you were using email.

Thanks for updating the README.

Please think about my suggestions for the options panel. I think some words are a bit confusing now - probably new users will agree with that more than people that are already used to it. That's why I tried to write down all my questions in the first time I used Ivy.

[abo-abo]

Please think about my suggestions for the options panel. I think some words are a bit confusing now - probably new users will agree with that more than people that are already used to it.

If you have concrete ideas, do share. So far, no one has complained about the options panel. I use it a bit and like the shortcuts. The descriptions are OK for me, as long as they keep the whole thing small. I wouldn't mind changing the descriptions to be more clear as long as they don't increase the size of the panel.

[Andre0991]

If you have concrete ideas, do share.

I mentioned a few in my first post. But I'll summarise them here.

So far, no one has complained about the options panel.

Most issues are about bugs, because them can completely break one's workflow.
It's rare to see issues on UI, especially because we can get used to it, even
when it doesn't make much sense, and we don't gain much reporting it. For
example, I could live with the fact that go is used to execute the selected
action. It's not a good a good word IMO, but it's usable.

I'm not writing this to know what the keys do. Even if the word for some action were called "foo", I would be able to just use it and discover what it does.

I use it a bit and like the shortcuts.

Again, you have been using this since day one so of course you are used to the
keybindings and the interface.

Here are my suggestions:

• I would remove those "Yes", "No" and "Maybe". The fact that an action leaves
  Ivy should already be clear depending on its colour, so "Yes" and "No" are
  redundant. I still don't know what "Maybe" does, but again, I don't think
  this information is useful anyway. Perhaps you may want to group the columns
  according to another criteria, that would be nice IMO.
• Change "Oops" to "quit". The latter is more familiar in Emacs.
• As I said, "done" can be misleading. I thought it would just quit Ivy, but
  what it actually quits Ivy and execute the action. "go" is similar, but it
  doesn't quit Ivy. Unfortunately, "go" doesn't tell anything about what it
  actually does either. Sorry, I don't have a good concrete suggestion here -
  this is not trivial actually. Perhaps "action" (= "go") and "action and quit"
  (= "done"). Or "execute", "run"... so there are two things here: make sure that the word makes it clear that it runs an action, and using the same word for both would be intuitive.
• I insist that having a visual clue for help would be beneficial. Not sure
  where I would put this though. Also, the content from the help would depend on
  the type of buffer where it was called, just like C-c ? in Helm.
  If you don't agree with this, I suggest at least documenting what all
  keybindings do in the options menu - I grep'd for "oops" and didn't find
  anything, for example.

[abo-abo]

I would remove those "Yes", "No" and "Maybe".

Done.

Change "Oops" to "quit". The latter is more familiar in Emacs.
As I said, "done" can be misleading. I thought it would just quit Ivy, but what it actually quits Ivy and execute the action. "go" is similar, but it doesn't quit Ivy.

These are mnemonic devices resulting from a limited set of single-key bindings. Being non-invasive and small is better in the long run than being overly descriptive.

I insist that having a visual clue for help would be beneficial.

I don't want to do it by default, perhaps you can get it in a spacemacs layer. However, I've added C-h m (ivy-help) that does a similar thing to Helm's C-c ?.

[Andre0991]

Cool. Thanks for your patience @abo-abo.