search

evantravers / Hyper.spoon

20 stars 2 forks source link

Documentation suggestions #5

Closed danielo515 closed 1 year ago

danielo515 commented 1 year ago

Hello, let me start this issue thanking you for your work with hammerspoon, specially the blog post you wrote about it through the years. I read them all (a couple of times each) and they were really inspired. I'm relatively new to HS, so take whatever I'm gonna say with a grain of salt. Also I'm the kind of person that doesn't get acronyms very well, so sorry if I look picky.

This module seems to be great. The idea of having a regular key (like F19) act as hyper is genius. I have a split, ortho, programmable mechanical keyboard, so having an hyper key is not a problem for me, but the wide range of options a hyper key that you can add modifiers to opens is hard to ignore.

My main problem with this spoon though is with documentation. The first sentence doesn't tell me much: I don't know about hs.hotkey.modal nor I know what PTT mean. Also I wish the concept of bindPassThrough was explained prior to its use. The example in the same readme is great, but it does not let me understand the concepts I already mentioned. I ended looking at the code, just to see that it was very simple, almost two clever functions and and smart usage of built-in modules. Until I wrote this issue I was not sure of what PTT mean in this context. A first google search leads to pointless resutls, but a second one showed that it means Push To Talk. Being used to normal Hyper key in my keyboard, this was not giving me any information, because I always had to keep the button pressed because that's how modifiers work. Just now, one paragraph above this one, I remembered that this is just a wrapper around hs.hotkey.modal, which made me thing that that module does not behave like that, and that is what this spoon provides: using hs.hotkey.modal like a modifier key, which in the default case just behaves like a normal key tap? I think clarifying the difference between this wrapper and the default module will help a lot new people to grasp it.

Sorry for the wall of text, but I just wanted to make sure that people reaching this great spoon are able to grasp what it does and why it exists.

Regards

evantravers commented 1 year ago

Thank you sir! I appreciate the kindness.

I'll add improving this documentation to my todo list, but if you want you can submit some pull requests with suggestions to help me along… it's a busy week.

Cheers!

evantravers commented 1 year ago

Well… I couldn't resist working on it. @danielo515, do you think the new version is clearer, or should we reopen this issue?

danielo515 commented 1 year ago

Hello @evantravers , thanks for your rapid and kind response and for taking into account the suggestions from some random guy on the internet.

The update looks good, and the explanation is much more clear now. Also thanks for updating the json documentation, it was confusing me why my IDE was telling me the methods didn't exist 😂 I really wish the readme needed less references, but that will mean to put more text into the readme, and people looking for this spoon probably know what they are after anyway, so I think it is OK. Thanks again.