I think there should be a hint for the #iex:break trick.
Edit: not sure if it fits into example hints that were shown above, but I think breaking from a borked expression is definitely a big gotcha. If it’s possible to capture ctrl+c and display once this hint, I think it would be useful.
Maybe something we could do instead of those hints is an interactive tutorial introduction? It would show the most important features of IEx, the h helper, the i helper, it would explain the stuff with lists, etc. I think it might be much more approachable. It should be strictly an introduction to IEx, and not the language to keep it short. It might give some links to more resources at the end.
Yes, it’s a “separate mode”, where you need to launch it explicitly, but I think it’s something small enough, and distinct enough, that we would be able to spread the word quickly. We could also allow launching the tutorial with tutorial() command from within IEx and show info about that in the banner that is displayed when you launch IEx.
Maybe we should go that far, and IEx should automatically enter the tutorial mode, when you first launch it.
This is assuming that you will get a bunch of extra help. We have only a single hint listed so far and it is displayed once per user in a computer. It is unlikely you will be in a situation where a bunch of hints are listed. Plus, IEx supports per user configuration on ~/.iex.exs.
This has also been explained above. An opt-in system is not going to be helpful because newcomers won’t be familar with the opt-in system and/or syntax.
The problem is not with learning Elixir. We already have plenty of mechanisms for learning Elixir, many of those comment on those “gotchas”, yet users still keep running into those scenarios. Not everyone will learn the language through elixir_tutorial or even through book for what matters. Many will jump straight into exercism and try to figure things out. Or many will learn about the Enum module from a blog post and jump straight into IEx and get confused with those results.
If our assumption is that “let’s have a way to learn the language where we can talk about this and everyone will go through it”, then we already have the Getting Started guide (and yet the problem still exists).
That’s why I explicitly said, that the tutorial shouldn’t be about learning the language, but IEx as a tool. As you said, there’s plenty of material for learning elixir, as a language - no point in duplicating it. The tutorial should be exclusively about IEx and how to use it, and some common things you might find - namely the charlists vs list of ints. For now the only things, I would include, would be the h helper, and the i helper with a charlist. Nothing more.
If we keep it minimal, I think it would be completely fine, to enter this mode when you first launch IEx on a machine so you’re “forced” in a way into the tutorial.
Whatever solution we choose, we need to find a good way to disable tutorial/hints when running in production. It would be extremely annoying to see all that stuff when you launch iex on heroku, for example, where each time you call heroku run iex you get a completely new “machine”.
The same answer still applies. We cannot assume that everyone will learn Elixir or IEx in a certain way. If we provide a tutorial, people won’t know about it. If we force it, people will skip it while upsetting many existing users of the language in the process. The whole point of hints is to not disrupt the workflow in the first place (and even after explicitly saying so, look at how many replies we have that are worried about disrupting their workflow).
I agree with this vision, and think it’s possible to have hints while avoiding too much disruption. We’ve established there will be a way to persistently disable the feature per machine. At worst veterans who find the hints disruptive will only need to disable them once. @Eiji smartly pointed out that a hint could explain how they can be disabled.
@josevalim’s original example would have helped me when I was getting used to IEx.
Even though I happened to understand how char lists are encoded, it caught me off guard the first time I saw one of my lists printed as a char list in IEx. Having a quick hint in that moment would have helped me get on with my day and be less anxious about potential gremlins in my machine doing things I don’t understand. Granted, it didn’t take too long to work out what was going on and why, but a hint would’ve helped. And remember,
Unfortunately I’m struggling to think of many other hints I’d like to see, but I bet pairing with a complete beginner would expose them. There’s probably some related to pattern matching gotchas, as that’s a foreign concept to most who have little experience with the ML language family.
Some of concerns about hints seem to be that we could end up with too many hints that aren’t useful. Perhaps we should also discuss how to gather useful feedback from users about individual hints.
One idea that comes to mind is giving each hint a unique ID like Rust does for its errors. When the Rust compiler emits an error it includes the error’s ID so you can query for more information, like this:
$ rustc --explain E0001
This error suggests that the expression arm corresponding to ...
When users file issues about errors they generally include the error ID. This makes it easier to find discussions about the particular error, and even see how its explanation text has evolved over time in response to these concerns.
Another potential benefit of assigning hints public IDs is we could someday support another hint mode called ‘terse’ which emits a hint ID and a one-line title. When users are interested in seeing more they can use a special command to see full explanation associated with that ID.
It is unfortunate that much of the discussion has focused on this concern because, as you said, we only have a single hint so far (with possibly another one being debated). At this point it is most likely this proposal won’t pass because it is not worthing working on this for a single hint. Assigning IDs, a terse mode, and other configurations are pointless if we don’t have hints to apply them to in the first place.
Reading through all of this again, I’d do this:
~/.iex.exs that the dev explicitly specified to false – which is IMO perfect.iex -q (quiet mode), maybe? Let the option be an explicit opt-out. I don’t think any of us would be so annoyed of seeing iex hints once a year (or only once at all, ever).heroku run -a <your-app> iex -q -S mix), a simple function call like IEx.hints(false) should provide a good alternative? I think this might be the main conflicting point right here – namely the people who can’t influence their CI setups in terms of exact CLI commands but who would still be annoyed by seeing hints every time they connect to a remote disposable container and execute a command that returns a charlist. I’d say for those people a flag in ~/.iex.exs should sort them. Deploying with anything that involves a bash script somewhere allows you to change a number of files, including ~/.iex.exs.Thoughts?
Please check my last comment. It is likely it was not there when you started re-reading. 
Everyone is worried about disabling hints on the wrong assumption it will be a verbose system and users will be showered with hints on usage. However, we will only emit single hint per IEx command and those hints will trigger on special occasions.
If I am running on Heroku, even if I have hints enabled, it is unlikely the hint will trigger and, if it does, it is easier to ignore the hint than remember some special function or flag I need to pass upfront. Sure we will provide such features but the focus on disabling has unfortunately side-tracked the discussion from what could have been more relevant topics.
I don’t think so. Most of us simply have notoriously bad experience with systems who never provided opt-out of features we didn’t need 99% of the time. So we’re getting kind of defensive here.
Please don’t take this the wrong way. On this forum, I’d say the most active users are experienced devs and this might skew (or side-track as you put it) discussions away from their intended core due to people wanting things done [mostly] right on the first go – but this shouldn’t be to the detriment of the discussions.
I absolutely believe this proposal must be moved forward to implementation.
@josevalim Don’t give up on this proposal! It will really help new and even experienced users. A one-time hint is perfect and I would not need a “turn off” setting (though it should be provided). If we come up with a decent amount of “gotchas”, we’re good to go.
Would there be anyway to have the hints showing in a connected terminal in a new window?
So on starting IEx it might say something like:
Would you like us to show you hints in a new window? Y for yes or N for no
If they say yes a new window would open and then every time an event occurs that triggers a hint it would show in that new window.
I think this could prevent any confusion arising from information overload. I am not sure about anyone else but I know that when I first started out things like Vim put me off because there was too much going on/to keep track off. This would also prevent interference with workflow and would make it more likely for experienced devs to turn this on (which will in turn make it more likely to get feedback/contributions).
With regards to hints themselves, if able to do them in a separate linked window like this - I say go to town 
and show a hint for every new item that is encountered:.
Hey! You just used a List. Did you know Lists in Elixir are linked-lists and have a head and a tail…
Cool, but what about when connecting from a text-only terminal?
Thanks everyone for the feedback.
I am closing this proposal until we are aware of more places where a potential hint system would be helpful. Once we have enough hints, then we can discuss display mechanisms, enabling/disabling, etc.
Just saw this thread, so apologies if I’m replying when it’s already closed.
I’ve seen people being puzzled when a struct which implements Inspect (e.g. MapSet) gets printed in a different form, maybe a hint would be useful there.
The opt-out approach of this feature looks like the way to go IMHO.
A place where I think a hint would be useful is the r function of iex. The documentation says:
Since typespecs and docs are loaded from the .beam file (they are not loaded in
memory with the module because there is no need for them to be in memory), they
are not reloaded when you reload the module.
Which I think that could be also a useful hint on the first r invocation.
I’ve also seen some confusion regarding the warning about module redefinition that appears after the module reloading. Some users think that they may have an error in their modules, while the warning is simply telling us that the module being reloaded. I’m talinkg about is this:
iex(3)> r MyProject.User
warning: redefining module MyProject.User (current version loaded from _build/dev/lib/my_project/ebin/Elixir.MyProject.User.beam)
apps/my_project/lib/my_project/models/user.ex:1
{:reloaded, MyProject.User, [MyProject.User]}
This could be made more understandable to users, but I’m not sure if this would fall into the errors must have better error messages rule. What do you think @josevalim?
A post was merged into an existing topic: What do you think is missing or needs improving in Elixir?
Rather than full text hints, could we create some knowledge base on the web?
So iex will just return the link to that knowledge base.
Enum.map([0, 1, 2], & &1 + 10)
'\n\v\f'
Hints: please visit https://elixir-lang.org/kb/45/ascii-char-in-single-quotes
With this kb, we can have better conversation when referring to hints.
“which hint are you talking about?”
“this one: https://elixir-lang.org/kb/110/genserver-call-and-cast”
and if you want to update the hint, you could just update the kb on the web.
© Copyright Elixir Forum | Terms | Privacy & Cookies
