Begginer issues with /intro - wording, UX, ((fn)) error ...
holyjak opened this issue · comments
Issue:
Maria is awesome! I have just tried the intro with a beginner and we run into a few issues that perhaps could be improved. Perhaps some of these could be turned into issues of their own?
(1) "Parens" is an unknown expression to normal people so I would add the bold part to this text:
circle is a function. By putting the function right after an open-parenthesis, we call that function. This makes the expression in parentheses (or parens for short) kind of like a sentence. In Clojure, sentences start with an open-parenthesis: (. Next in the Clojure sentence is the verb, in this case, circle. The verb is usually a function. Whatever comes after the function "verb" are the arguments we want to give to the function. When we evaluate an expression in parens it calls the function...
(2) UX: Parens are way too light-colored and hard to see, which makes it also difficult to separate individual sub-expressions. Darker color would be better. (Especially if the reader has weak sight.)
(3) Perhaps start with Shift-Ctrl-Enter and only introduce Ctrl-Enter later - it is easy to misplace the cursor and become confused as to why you get just 25 instead of a circle. This is only explained later in the tutorial. Alternatively, check the result of the evaluation against what the tutorial does expect and provide a helpful message if they don't, such as (when (input code is as expected and output != shape) (message "Why are you not seeing a shape? You have likely placed your cursor inside the expression and evaluated only a part of it. Place it after the closing ) and evaluate it again.")
(4) Error message for ((shape 20)) is not friendly - "shapes.core.circle.call(...).call is not a function"
(5) (doc layer) uses so far unexplained & in [& shapes] - perhaps it should be explained?
(6) Under "Shapes and Colors" this is unclear and confusing (it certainly confused me):
⬇ your code goes here 😀 (press "return" or "enter" twice with the
cursor there)
⬆ your code goes here
It would be better to actually provide the empty line for the code there, perhaps with a blinking cursor where the user is expected to start typing
Let me know if I can help in any way!
Environment:
- Browser: Firefox
- Platform (Mac/Windows/Linux): Mac
URL to a gist replicating the issue (if possible/relevant)
-
You raise a good point, but I disagree with the solution. Since we only use "parens" once (and "paren" once) in the document, I'd rather remove those references than spend words explaining them. Would you be interested in making a PR for that?
-
We'll discuss visibility of parens, thanks for reporting
-
Noted, will consider. See new wiki page: https://github.com/mhuebert/maria/wiki/Confusion-Sources
-
I added an entry to our error wiki. Do you have edit rights to the wiki?
-
It's unfortunate that unexplained things crop up in the intro curriculum, but it can't always be avoided. In this case it may not be worth explaining the ampersand, nor somehow avoiding its presence. It's possible this will remain a question for on-site coaches to tackle, or for newbies going through the course online to be forced to ask the community.
-
Noted. We specifically chose to force the user to create the code block because it's functionality we want them to know how to do.
I appreciate your feedback. Next time it may be better to split separate concerns into separate tickets, so they can be tracked individually. As it is we may need to close this before all points are resolved.
Perhaps start with Shift-Ctrl-Enter and only introduce Ctrl-Enter later
this just made me realize that we updated the keybindings without updating our guide - the binding for evaluating an entire cell is now just Shift-Enter, no need for command/ctrl (though that still works).
Error message for ((shape 20))
This may well be a recent regression, I updated Maria to the latest ClojureScript versions and haven't thoroughly tested error messages.
re: function error message - I spoke too soon; the problem is that our pattern-matching for error messages isn't matching maria.user.hello.call(...).call as a single item to match on (it splits on each "." or paren). See here for the pattern and line 29 for the tokenizer.
I'm interested to try and contribute. Which of these points are to be converted to their own issues?
I'm interested to:
- Create the "sub-issues" for this multi-issue post
- Attempt to fix one or more bugs
- Brainstorm on education strategies to meet learner & teacher needs
- Create new notebooks to meet other needs