Thanks for working on these "casual" Emacs packages. I've long thought it is lamentable that we mostly have two kinds of UIs:
* Those designed for power user speed, with seemingly little regard to novice-friendliness (e.g. bash, tar, find, Emacs calc, Vim).
* Those designed for novice-friendliness and aesthetics, with seemingly little regard to power user speed (many GUI programs, almost all websites, almost all phone apps).
It feels like we're very far from the Pareto frontier, and I wish more people thought explicitly in terms of getting closer to that frontier - that is, "how can we maximize novice-friendliness under the constraint of not lowering the speed ceiling even a bit". I think this could be done through some combination of autocompletion, cheatsheets that pop up automatically, and consistency between programs.
Magit-like UIs are a happy exception to the rule. Their speed ceiling is very high because they're completely keyboard-driven and have no animations, but their discoverability is good because they constantly pop up little cheatsheets of what keys you can press to trigger actions. I was able to start using Magit almost immediately after installing it, and learn it gradually without looking at external resources. Now I fly through the common operations on muscle memory, and it feels like it took no effort to get there. I hope that more programs copy this UI paradigm.
> Magit-like UIs… speed ceiling is very high because they're completely keyboard-driven and have no animations, but their discoverability is good because they constantly pop up little cheatsheets of what keys you can press to trigger actions.
This is the kernel of brilliance: there is zero slowdown when using Magit if you're proficient. Easy for beginners to start exploring (it's a very discoverable UI!) and there's little to nothing to do for experts to start using it faster. Sure, there are some things you can tweak, but the interface is already so geared towards efficient use that it just works as-is.
I'm very happy that the `transient` package has been merged into Emacs; hopefully we'll see more like Magit and Casual popping up in the future.
While I didn't submit this link to HN, I wrote the OP. Thanks for the compliment on Casual! It's been an exercise in re-litigating my user experience with Emacs this Summer, which I've decided early on to share publicly. For folks interested learning more about the Casual packages, here's a link to Casual Suite (https://github.com/kickingvegas/casual-suite). At my blog you can find all my posts on the different Casual packages. http://yummymelon.com/devnull/
Looking at some of these screenshots, this is such a fantastic idea that it is surprising it wasn't done earlier. Magit has the perfect interface, why shouldn't everything be like that? Who wants to read the Info manual anyway? Info, Dired, Calc, obviously. Org mode, of course.
Maybe other people have been working separately on similar ideas? Really it is extremely obvious in retrospect that everything should have a Magit style interface. Ultimately, it would be great if that were the default, generally assumed style throughout Emacs. It would be great if all that effort could be coordinated and merged into the main distribution. Built-in, no external packages.
Magit should be the subject of a book about progressive derivative UX enhancement, and even passive pedagogy. Often tarsius and the team managed to make you curious and try ideas, like selecting a range of lines and hope staging would only stage it and not the whole diff range. You don't even make an effort cause it's one key down and one key to undo on case it's not what you expect. It's cozy to the point of brilliance.
My opinion is that your ideas of "user friendliness" are misguided. I think a better way to phrase what you're trying to say is that, there is a class of software that have user manuals and require a flip-through, and there is a class of software that locks its users into predefined tracks so they can only ever pick from the choices presented to them.
I don't think there is anything unfriendly about needing a manual. If only all software could be so thoroughly documented! It used to be, back in the 80s and 90s, and it was a better time. I mean, isn't it a disservice to, in an analogy, give a user a kayak without a paddle?
In the 1970s, secretaries who had not used computers found it easy to use Emacs and program in LISP. [1] And I, personally, was a voracious reader of software manuals when I was a small child. And they made the world make sense, and they made me a smarter person for it. And I really do believe that people waste more of their lives picking ill-suited preset choices than they would if they (could have) just read a manual.
I think you misunderstood what rms said there (but if the transcript is accurate, he was unclear).
Yes, Multics Emacs was the one used by secretaries (except at AI & LCS where they used TECO EMACS on ITS). In both cases most of the extending by non-programmers was done with macros (`c-X (` which is still that command today).
Multics Emacs had an excellent design and you could in fact write some very simple functions with a copy-and-modify rote approach (nothing wrong with that!). But beyond that I never met one whom one could describe as knowing Lisp. In fact most would have been intimidated if you'd told them that they could improve the editor by "programming".
This "programming is impossibly hard for a person like me" attitude was a bad cultural property of the 1970s, thankfully now somewhat in the past. But that change depended on direct work on the problem by people like Seymour Papert and Cynthia Solomon in the LOGO lab (part of the AI lab).
Excel is a great (in volume and reach) example of this: many people write very complex and sophisticated programs in Excel and still don't believe they can program. Now Python is embedded in Excel some people can be tricked into writing real programs. And, presumably, tricked into running sophisticated malware!
What excel got right is making the state visible. You don’t have to track it through variables and thinking about invariant. It’s a graphic REPL. Smalltalk is close too, but it is way too powerful for casual uses.
> I don't think there is anything unfriendly about needing a manual.
It is, however, very user friendly if something is designed such that a user never has to look at a manual.
If someone makes an interface where you can do quite a bit without ever reading one, and you read it only for the finer points, that's also pretty user friendly.
I never read a manual to use my smartphone when I bought my first one. I think most people will agree that if you buy a smartphone and you can't do anything on it until you read a fantastically well written manual, they will consider the phone to be user unfriendly.
A smartphone is very restricted in interaction. You can learn most of the patterns by just playing with it. Yo will still need the manual to do stuff that requires sequences of actions
The terminal is even more restricted, but it has greater versality because commands can be anything. You don’t go to the manual to learn how to use a terminal, you go to it to learn what are the commands and their parameter. And the shell that evaluates the command can be complex enough to require its own manual.
TUIs are more like musical instruments (without the tangibility). You can discover pretty easily that hitting the keys produces sounds, but playing a piece well requires training and a lot of music theory to communicate with fellow musicians. It seems fair that operating a computer requires the same thing.
> there is a class of software that have user manuals and require a flip-through, and there is a class of software that locks its users into predefined tracks so they can only ever pick from the choices presented to them.
I think that this is a false dichotomy most of the time. Yes, there comes a point where to get more novice-friendliness, you have to trade off against the program's skill ceiling - its flexibility and the speed that a proficient user can achieve with it. But are we at that point? Have we really picked all the low-hanging fruit so that the only remaining way to decrease the need for manuals is to "lock the users into predefined tracks", as you say? Personally, I don't think we're even close. There seems to be very little exploration of that space. Apart from rare exceptions like Magit, I mostly see software that's designed to appeal to beginners, and then "power user UIs" that are either really old or imitate UIs that are really old.
Magit is actually a great counterexample to your framing. It turns your keyboard into a huge joystick for git commands, without forcing you into any particular git workflow. It's easy to integrate your own custom git subcommands into Magit. If some obscure thing you want to do isn't supported, there's a key to run a custom git command, or you can just do it in your shell and then hit the refresh key in Magit. Yet, because Magit shows you a lot of contextual information about your repository, as well as the keys you can press to perform various actions, it requires very little manual-reading to learn.
Or let's take shells as another example. Would it really "lock the users into predefined tracks" to make some part of the prompt bright red when you are root? To have the hostname in the prompt when you're logged in via ssh, so that it's harder to mess up and execute a command in a different window than you intended? When you try to run a program that doesn't exist, instead of just saying "command not found", to tell you the name of the command you appear to have misspelled, or the package you can install to get the command? When you start typing a tar command, to show you a little cheatsheet of the common flags? To have autocompletion for all the flags of the command you're typing, along with a short sentence describing each? To have a bit of syntax highlighting, so that you know right away when you've typed a command or a path that doesn't exist, because it's in a different color? To have the default variable syntax pass the value as-is, and use a special syntax for word-splitting, rather than the reverse? To have a fuzzy search window for the last thousand commands you've executed and directories you've visited? To pop up a desktop notification when a very long-running command has finished? To measure the running time of every command and make it accessible afterwards with a command or a variable, so that you don't have to re-run the command if you forgot to prepend "time" to it? To make the shell act a bit more like a Jupyter notebook, so that it's easy to run multiple commands in parallel, and you can have keybindings that scroll the window by command rather than by screenful? To show the contents of the current directory at all times below the prompt or in an optional side pane, so that it's easier to orient yourself in the filesystem without running ls all the time?
I don't think any of these things would "lock the users into predefined tracks". It seems to me that they would make life easier for novice users without hurting power users, and it's mostly for historical reasons that we don't have them by default.
Your example of a fully programmable text editor is probably the strongest. Emacs would indeed be more novice-friendly if its programming language was removed in favor of a couple pages of GUI settings, and I wouldn't want that. But after we've decided that Lisp programming it is, are there really no things that could be done to make it more approachable without lowering the skill ceiling? What about good default settings? Highlighting matching parentheses? On-by-default autocompletion that pops up a little window with the documentation of the item that you're about to select? Highlighting functions that are defined in the current Emacs instance with a subtly different color from those that aren't? Showing the user the signature of the function they're typing at the bottom of the screen, so that they don't need to open the docs if they're a bit rusty and forgot the order of its arguments? Showing all references, a link to the manual, and the source code of the function you're viewing in *Help*?
Lastly, your distinction of whether a program needs you to read the manual before use strikes me as too binary. There's also the matter of forgetting things over time. I think it's more accurate to think of each UI as having a range of usage frequencies that it's best for. For example, I know common Emacs, Vim, and Magit keybindings by heart because I do a lot of programming and quite a bit of system administration. But when I need to partition a drive, I just use GParted. I only do it once a year or so; it doesn't make sense for me to learn a command-line tool, as I would probably forget the syntax by the time I needed to partition something again. If I was partitioning drives all the time, then it would be different.
Defining good default is the hardest because everyone expect something different. Even is magit is great, it also requires an understanding of git and emacs. What it offers is a streamline usage of git.
You can make things more approachable but that’s code that you have to write and maintain while there are other way to get the same information. It’s more efficient to get the user to read the manual (lifetime benefits) than making the software beginner-friendly (useful only at the beginner stage and complex code)
Well said. The Magit interface is such a pleasure to use, sometimes I will modify and rearrange commits just for fun. A Magit-style interface for Calc seems like a great idea.
New spacemacs user here. When I'm on the magit pane (SPC g s) what commands are available to me and how am I supposed to know? I know I can do 'p' to enter a push menu and 'r' will give me a rebase menu, but that's pretty much all I know.
If you press '?' in the magit window a popup of available commads should appear. If I remember correctly from when I used to use DOOM emacs before switching to vanilla, evil (vi emulation) keybingings mean the keys listed in the magit popup are incorrect, however it should give you an idea of what commands are available and you can use other Emacs help facilities to find the Spacemacs keybindings.
The best UI is for a cheat sheet to pop up after a delay, so you can proceed without a delay if you know, but also not have to press anything else if you don't know, just wait a bit.
Whenever I find myself learning about something where I know that I will not use it frequently enough to actually remember its keystrokes/commands/etc. I create a new “personal documentation” for it as an .org file (I have a central folder and a git repo for all of them). Here I’ll write all the information (like keybindings, details of commands, common procedures, concepts, etc.) down that is specific to my own use-cases and organize it in a way that makes sense to me.
It takes some time and effort and may seem redundant when there is good documentation out there already (as with most of Emacs). But still I find myself wasting a lot of time looking for that one piece of information in the docs where I forgot how to even search for it. Maybe it works so well for me because I kind-of enjoy the process of writing it (which many people might not). But I feel much less frustrated afterwards when I come back to some tool or language after years of not using it and find it really easy to remember what was important to me at the time and how to do X.
Tools like Casual Calc are great because they reduce the need to do that manual work of going through the docs and writing down what one want to remember in a (for them) more clear/concise/practical way. However, the way they select and organize knowledge/commands only reflect the common use cases, so there may still be a need to write stuff down.
As a more general helper, I really like to use Emacs Calc with `which-key`, which provides a similar interface to see what keybindings are available under a specific prefix-key. What also helps is if you press `h` and then search for a specific function (`h f`), key (`h k`), etc. or just type `x` to enter a function name directly (or by keyword using text-completion).
I used to do the same (self document in an org file). With Emacs, though, I've found creating hydras[1] to be a better approach. It looks a lot more complicated than it is. The first time I wrote hydras, it was hard. After that, it's been trivial.
Of course, magit like menus are mildly superior to hydras, but I don't know if they are as easy to generate.
I am also a big fan of hydras, but I use them more for workflow things like window movement, editing org tables or quicker navigation in org headings/trees and it complements my keybinding system in `meow`[1] (similar to Evil or the Kakoune/Helix text editing scheme).
That's one use case, but you can use them to execute any elisp code. So when I encounter a new major mode I plan to use, while going through its docs I make hydras for keystrokes/commands I plan to use. This way I don't need to look up my notes, nor do I need to memorize keystrokes.
I create ad-hoc shell scripts or alias anytime the commands get complex. If I find myself reusing them in other contexts, I add them to my bashrc files or create proper scripts to add to my home bin.
That’s why I dislike macOS these days. Not many software bother with scripting interface and the increasing IOS-ication makes it a chores for power users (still great if your usage is confined to a few apps).
You might like (contributing to) https://github.com/tldr-pages/tldr, I'm sure your notes would be helpful to me and others! Not sure if they've got a section for specific editor packages, yet.
Thanks for working on these "casual" Emacs packages. I've long thought it is lamentable that we mostly have two kinds of UIs:
* Those designed for power user speed, with seemingly little regard to novice-friendliness (e.g. bash, tar, find, Emacs calc, Vim).
* Those designed for novice-friendliness and aesthetics, with seemingly little regard to power user speed (many GUI programs, almost all websites, almost all phone apps).
It feels like we're very far from the Pareto frontier, and I wish more people thought explicitly in terms of getting closer to that frontier - that is, "how can we maximize novice-friendliness under the constraint of not lowering the speed ceiling even a bit". I think this could be done through some combination of autocompletion, cheatsheets that pop up automatically, and consistency between programs.
Magit-like UIs are a happy exception to the rule. Their speed ceiling is very high because they're completely keyboard-driven and have no animations, but their discoverability is good because they constantly pop up little cheatsheets of what keys you can press to trigger actions. I was able to start using Magit almost immediately after installing it, and learn it gradually without looking at external resources. Now I fly through the common operations on muscle memory, and it feels like it took no effort to get there. I hope that more programs copy this UI paradigm.
> Magit-like UIs… speed ceiling is very high because they're completely keyboard-driven and have no animations, but their discoverability is good because they constantly pop up little cheatsheets of what keys you can press to trigger actions.
This is the kernel of brilliance: there is zero slowdown when using Magit if you're proficient. Easy for beginners to start exploring (it's a very discoverable UI!) and there's little to nothing to do for experts to start using it faster. Sure, there are some things you can tweak, but the interface is already so geared towards efficient use that it just works as-is.
I'm very happy that the `transient` package has been merged into Emacs; hopefully we'll see more like Magit and Casual popping up in the future.
Am I crazy, or is this how most computer UIs worked before modern GUIs? IIUC most/many POS systems still work like this.
You're not wrong. Building a TUI is basically the same as mainframe forms programming.
While I didn't submit this link to HN, I wrote the OP. Thanks for the compliment on Casual! It's been an exercise in re-litigating my user experience with Emacs this Summer, which I've decided early on to share publicly. For folks interested learning more about the Casual packages, here's a link to Casual Suite (https://github.com/kickingvegas/casual-suite). At my blog you can find all my posts on the different Casual packages. http://yummymelon.com/devnull/
Looking at some of these screenshots, this is such a fantastic idea that it is surprising it wasn't done earlier. Magit has the perfect interface, why shouldn't everything be like that? Who wants to read the Info manual anyway? Info, Dired, Calc, obviously. Org mode, of course.
Maybe other people have been working separately on similar ideas? Really it is extremely obvious in retrospect that everything should have a Magit style interface. Ultimately, it would be great if that were the default, generally assumed style throughout Emacs. It would be great if all that effort could be coordinated and merged into the main distribution. Built-in, no external packages.
Magit should be the subject of a book about progressive derivative UX enhancement, and even passive pedagogy. Often tarsius and the team managed to make you curious and try ideas, like selecting a range of lines and hope staging would only stage it and not the whole diff range. You don't even make an effort cause it's one key down and one key to undo on case it's not what you expect. It's cozy to the point of brilliance.
My opinion is that your ideas of "user friendliness" are misguided. I think a better way to phrase what you're trying to say is that, there is a class of software that have user manuals and require a flip-through, and there is a class of software that locks its users into predefined tracks so they can only ever pick from the choices presented to them.
I don't think there is anything unfriendly about needing a manual. If only all software could be so thoroughly documented! It used to be, back in the 80s and 90s, and it was a better time. I mean, isn't it a disservice to, in an analogy, give a user a kayak without a paddle?
In the 1970s, secretaries who had not used computers found it easy to use Emacs and program in LISP. [1] And I, personally, was a voracious reader of software manuals when I was a small child. And they made the world make sense, and they made me a smarter person for it. And I really do believe that people waste more of their lives picking ill-suited preset choices than they would if they (could have) just read a manual.
[1]: https://www.gnu.org/gnu/rms-lisp.en.html
I think you misunderstood what rms said there (but if the transcript is accurate, he was unclear).
Yes, Multics Emacs was the one used by secretaries (except at AI & LCS where they used TECO EMACS on ITS). In both cases most of the extending by non-programmers was done with macros (`c-X (` which is still that command today).
Multics Emacs had an excellent design and you could in fact write some very simple functions with a copy-and-modify rote approach (nothing wrong with that!). But beyond that I never met one whom one could describe as knowing Lisp. In fact most would have been intimidated if you'd told them that they could improve the editor by "programming".
This "programming is impossibly hard for a person like me" attitude was a bad cultural property of the 1970s, thankfully now somewhat in the past. But that change depended on direct work on the problem by people like Seymour Papert and Cynthia Solomon in the LOGO lab (part of the AI lab).
Excel is a great (in volume and reach) example of this: many people write very complex and sophisticated programs in Excel and still don't believe they can program. Now Python is embedded in Excel some people can be tricked into writing real programs. And, presumably, tricked into running sophisticated malware!
What excel got right is making the state visible. You don’t have to track it through variables and thinking about invariant. It’s a graphic REPL. Smalltalk is close too, but it is way too powerful for casual uses.
> I don't think there is anything unfriendly about needing a manual.
It is, however, very user friendly if something is designed such that a user never has to look at a manual.
If someone makes an interface where you can do quite a bit without ever reading one, and you read it only for the finer points, that's also pretty user friendly.
I never read a manual to use my smartphone when I bought my first one. I think most people will agree that if you buy a smartphone and you can't do anything on it until you read a fantastically well written manual, they will consider the phone to be user unfriendly.
A smartphone is very restricted in interaction. You can learn most of the patterns by just playing with it. Yo will still need the manual to do stuff that requires sequences of actions
The terminal is even more restricted, but it has greater versality because commands can be anything. You don’t go to the manual to learn how to use a terminal, you go to it to learn what are the commands and their parameter. And the shell that evaluates the command can be complex enough to require its own manual.
TUIs are more like musical instruments (without the tangibility). You can discover pretty easily that hitting the keys produces sounds, but playing a piece well requires training and a lot of music theory to communicate with fellow musicians. It seems fair that operating a computer requires the same thing.
> there is a class of software that have user manuals and require a flip-through, and there is a class of software that locks its users into predefined tracks so they can only ever pick from the choices presented to them.
I think that this is a false dichotomy most of the time. Yes, there comes a point where to get more novice-friendliness, you have to trade off against the program's skill ceiling - its flexibility and the speed that a proficient user can achieve with it. But are we at that point? Have we really picked all the low-hanging fruit so that the only remaining way to decrease the need for manuals is to "lock the users into predefined tracks", as you say? Personally, I don't think we're even close. There seems to be very little exploration of that space. Apart from rare exceptions like Magit, I mostly see software that's designed to appeal to beginners, and then "power user UIs" that are either really old or imitate UIs that are really old.
Magit is actually a great counterexample to your framing. It turns your keyboard into a huge joystick for git commands, without forcing you into any particular git workflow. It's easy to integrate your own custom git subcommands into Magit. If some obscure thing you want to do isn't supported, there's a key to run a custom git command, or you can just do it in your shell and then hit the refresh key in Magit. Yet, because Magit shows you a lot of contextual information about your repository, as well as the keys you can press to perform various actions, it requires very little manual-reading to learn.
Or let's take shells as another example. Would it really "lock the users into predefined tracks" to make some part of the prompt bright red when you are root? To have the hostname in the prompt when you're logged in via ssh, so that it's harder to mess up and execute a command in a different window than you intended? When you try to run a program that doesn't exist, instead of just saying "command not found", to tell you the name of the command you appear to have misspelled, or the package you can install to get the command? When you start typing a tar command, to show you a little cheatsheet of the common flags? To have autocompletion for all the flags of the command you're typing, along with a short sentence describing each? To have a bit of syntax highlighting, so that you know right away when you've typed a command or a path that doesn't exist, because it's in a different color? To have the default variable syntax pass the value as-is, and use a special syntax for word-splitting, rather than the reverse? To have a fuzzy search window for the last thousand commands you've executed and directories you've visited? To pop up a desktop notification when a very long-running command has finished? To measure the running time of every command and make it accessible afterwards with a command or a variable, so that you don't have to re-run the command if you forgot to prepend "time" to it? To make the shell act a bit more like a Jupyter notebook, so that it's easy to run multiple commands in parallel, and you can have keybindings that scroll the window by command rather than by screenful? To show the contents of the current directory at all times below the prompt or in an optional side pane, so that it's easier to orient yourself in the filesystem without running ls all the time?
I don't think any of these things would "lock the users into predefined tracks". It seems to me that they would make life easier for novice users without hurting power users, and it's mostly for historical reasons that we don't have them by default.
Your example of a fully programmable text editor is probably the strongest. Emacs would indeed be more novice-friendly if its programming language was removed in favor of a couple pages of GUI settings, and I wouldn't want that. But after we've decided that Lisp programming it is, are there really no things that could be done to make it more approachable without lowering the skill ceiling? What about good default settings? Highlighting matching parentheses? On-by-default autocompletion that pops up a little window with the documentation of the item that you're about to select? Highlighting functions that are defined in the current Emacs instance with a subtly different color from those that aren't? Showing the user the signature of the function they're typing at the bottom of the screen, so that they don't need to open the docs if they're a bit rusty and forgot the order of its arguments? Showing all references, a link to the manual, and the source code of the function you're viewing in *Help*?
Lastly, your distinction of whether a program needs you to read the manual before use strikes me as too binary. There's also the matter of forgetting things over time. I think it's more accurate to think of each UI as having a range of usage frequencies that it's best for. For example, I know common Emacs, Vim, and Magit keybindings by heart because I do a lot of programming and quite a bit of system administration. But when I need to partition a drive, I just use GParted. I only do it once a year or so; it doesn't make sense for me to learn a command-line tool, as I would probably forget the syntax by the time I needed to partition something again. If I was partitioning drives all the time, then it would be different.
Defining good default is the hardest because everyone expect something different. Even is magit is great, it also requires an understanding of git and emacs. What it offers is a streamline usage of git. You can make things more approachable but that’s code that you have to write and maintain while there are other way to get the same information. It’s more efficient to get the user to read the manual (lifetime benefits) than making the software beginner-friendly (useful only at the beginner stage and complex code)
Well said. The Magit interface is such a pleasure to use, sometimes I will modify and rearrange commits just for fun. A Magit-style interface for Calc seems like a great idea.
New spacemacs user here. When I'm on the magit pane (SPC g s) what commands are available to me and how am I supposed to know? I know I can do 'p' to enter a push menu and 'r' will give me a rebase menu, but that's pretty much all I know.
If you press '?' in the magit window a popup of available commads should appear. If I remember correctly from when I used to use DOOM emacs before switching to vanilla, evil (vi emulation) keybingings mean the keys listed in the magit popup are incorrect, however it should give you an idea of what commands are available and you can use other Emacs help facilities to find the Spacemacs keybindings.
The best UI is for a cheat sheet to pop up after a delay, so you can proceed without a delay if you know, but also not have to press anything else if you don't know, just wait a bit.
Does https://github.com/justbur/emacs-which-key not work with spacemacs?
try the ? key
Whenever I find myself learning about something where I know that I will not use it frequently enough to actually remember its keystrokes/commands/etc. I create a new “personal documentation” for it as an .org file (I have a central folder and a git repo for all of them). Here I’ll write all the information (like keybindings, details of commands, common procedures, concepts, etc.) down that is specific to my own use-cases and organize it in a way that makes sense to me.
It takes some time and effort and may seem redundant when there is good documentation out there already (as with most of Emacs). But still I find myself wasting a lot of time looking for that one piece of information in the docs where I forgot how to even search for it. Maybe it works so well for me because I kind-of enjoy the process of writing it (which many people might not). But I feel much less frustrated afterwards when I come back to some tool or language after years of not using it and find it really easy to remember what was important to me at the time and how to do X.
Tools like Casual Calc are great because they reduce the need to do that manual work of going through the docs and writing down what one want to remember in a (for them) more clear/concise/practical way. However, the way they select and organize knowledge/commands only reflect the common use cases, so there may still be a need to write stuff down.
As a more general helper, I really like to use Emacs Calc with `which-key`, which provides a similar interface to see what keybindings are available under a specific prefix-key. What also helps is if you press `h` and then search for a specific function (`h f`), key (`h k`), etc. or just type `x` to enter a function name directly (or by keyword using text-completion).
I used to do the same (self document in an org file). With Emacs, though, I've found creating hydras[1] to be a better approach. It looks a lot more complicated than it is. The first time I wrote hydras, it was hard. After that, it's been trivial.
Of course, magit like menus are mildly superior to hydras, but I don't know if they are as easy to generate.
[1] https://github.com/abo-abo/hydra
I am also a big fan of hydras, but I use them more for workflow things like window movement, editing org tables or quicker navigation in org headings/trees and it complements my keybinding system in `meow`[1] (similar to Evil or the Kakoune/Helix text editing scheme).
[1]: https://github.com/meow-edit/meow
That's one use case, but you can use them to execute any elisp code. So when I encounter a new major mode I plan to use, while going through its docs I make hydras for keystrokes/commands I plan to use. This way I don't need to look up my notes, nor do I need to memorize keystrokes.
I create ad-hoc shell scripts or alias anytime the commands get complex. If I find myself reusing them in other contexts, I add them to my bashrc files or create proper scripts to add to my home bin.
That’s why I dislike macOS these days. Not many software bother with scripting interface and the increasing IOS-ication makes it a chores for power users (still great if your usage is confined to a few apps).
You might like (contributing to) https://github.com/tldr-pages/tldr, I'm sure your notes would be helpful to me and others! Not sure if they've got a section for specific editor packages, yet.
I feel like the existance of "casual" is a symptom of transient being way too hard to understand
Creating the menu is hardly the issue. Knowing the API of the package and setting good ergonomic keybindings is.