New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

More explicit documentation and UI suggestions #376

Closed
Andre0991 opened this Issue Feb 3, 2016 · 7 comments

Comments

Projects
None yet
2 participants
@Andre0991
Contributor

Andre0991 commented Feb 3, 2016

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:

screenshot 2016-02-03 19 13 11

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

This comment has been minimized.

Show comment
Hide comment
@abo-abo

abo-abo Feb 3, 2016

Owner

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鈥檚 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.

Owner

abo-abo commented Feb 3, 2016

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鈥檚 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.

abo-abo added a commit that referenced this issue Feb 3, 2016

@Andre0991

This comment has been minimized.

Show comment
Hide comment
@Andre0991

Andre0991 Feb 3, 2016

Contributor

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.

Contributor

Andre0991 commented Feb 3, 2016

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 Andre0991 referenced this issue Feb 3, 2016

Closed

spacemacs-ivy: Information and Suggestions #4540

6 of 6 tasks complete

@Andre0991 Andre0991 changed the title from More explicit documentation to More explicit documentation and UI suggestions Feb 3, 2016

@Andre0991

This comment has been minimized.

Show comment
Hide comment
@Andre0991

Andre0991 Feb 3, 2016

Contributor

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.

Contributor

Andre0991 commented Feb 3, 2016

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

This comment has been minimized.

Show comment
Hide comment
@abo-abo

abo-abo Feb 4, 2016

Owner

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.

Owner

abo-abo commented Feb 4, 2016

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

This comment has been minimized.

Show comment
Hide comment
@Andre0991

Andre0991 Feb 4, 2016

Contributor

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.
Contributor

Andre0991 commented Feb 4, 2016

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 abo-abo closed this in 00f08f7 Feb 4, 2016

@abo-abo

This comment has been minimized.

Show comment
Hide comment
@abo-abo

abo-abo Feb 4, 2016

Owner

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 ?.

Owner

abo-abo commented Feb 4, 2016

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

This comment has been minimized.

Show comment
Hide comment
@Andre0991

Andre0991 Feb 4, 2016

Contributor

Cool. Thanks for your patience @abo-abo.

Contributor

Andre0991 commented Feb 4, 2016

Cool. Thanks for your patience @abo-abo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment