more TMI in error message

[shriram]

I thought we'd got most of the overly verbose error messages, but we seem to have missed a few. For instance:

Many high-school students won't even understand several of the words: "if and only if", equal-always (what's that?), "satisfied", "operand" (I thought we were using just "left" and "right"?), "applied"…and there's passive speech without a clear reason. Also "reported failure" (I'm envisioning something like this: http://l7.alamy.com/zooms/c0cfe7d427a34cc198ca24a7515b3d85/1930s-businessman-talking-on-public-pay-telephone-in-phone-booth-cmt448.jpg).

[jswrenn]

I've addressed this in brownplt/pyret-lang@71005da7f5e891f8549e5244314130a254e89eba (and updated tests accordingly in brownplt/code.pyret.org@857bcecec834727281eda3d85ef3961c252faf10):

Looking at that screenshot, I realize I forgot to change "evaluated to" to "was"; I'll do that now.

[jswrenn]

Screenshot of the message as of 10e112bea06fc2fff61c103125e8c06bf83b5ea6:

@shriram Can I mark this issue horizon-fixed?

[jpolitz]

What about "Didn't pass this test", or "Didn't pass this is test" for the before-code part?

I don't really know if "test operator" adds much here.

[justinpombrio]

This "is" test failed because the [left] and [right] sides were not equal:

...

The [left] side was:

...

The [right] side was:

...

On Sep 21, 2016 15:35, "Joe Politz" notifications@github.com wrote:

What about "Didn't pass this test", or "Didn't pass this is test" for the before-code part?

I don't really know if "test operator" adds much here.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/brownplt/pyret-lang/issues/870#issuecomment-248719058, or mute the thread https://github.com/notifications/unsubscribe-auth/AAajAphPZkWxAEWtZg_GQwcbjp_dp0d8ks5qsYcLgaJpZM4KBmds .

[shriram]

And so many… words!

And bit words, too: "It succeeds if": “succeeds”! Are we really using “succeeds” everywhere? Does + only succeed if both operands are numbers?

[jswrenn]

Are we really using “succeeds” everywhere?

The use of "success" and "failure" to describe the behavior of the testing operators is taken straight from the docs.

Does + only succeed if both operands are numbers?

No, for functions, we talk about the function expecting certain things.

[shriram]

Right. Those were meant to be leading questions. As I've said before, in this very setting, the docs are not authoritative texts; in fact, we should assume this is the first attempt to comprehensively dictate a crisp and consistent vocabulary for Pyret, which we can then carry through everything. (Which is why I suggested making a vocabulary document à la Guillaume's for Racket.) The error messages should control the docs, not the other way around.

[jswrenn]

The error messages should control the docs, not the other way around.

Interesting.

And big words, too [...]

I don't think number of letters a word has is generally a good proxy for estimating our user's comprehension of a word. By some counts, 'success' is a top-1000 word (which would make it fair game for Randall Munroe's Thing Explainer). Can you explain your criticism a bit more?

[shriram]

A lot of our users are or are going to be

• younger readers, who are still slow at reading • teenagers, who are impatient • non-native speakers of English, for whom reading English is difficult

Every word counts. Every pixel of screen acreage also counts.

[jswrenn]

I understand all of those concerns, but not in relation to "success". What's a word we could use instead?

[jpolitz]

How about:

Didn't pass this is test:

<code>

The [left] and [right] sides were not equal. # could even be "were not the same"

The left side was:

<value>

The right side was:

<value>

[blerner]

I worry that if we simplify the "were not equal" wording too much, that we lose the informativeness that we have in explaining the differences in is, is==, is=~ and is<=>. I don't think we should say "were not always equal (because you chose to use equal-always by dint of using is)", but I don't think we should lose the deliberate association with "equality is tricky"...

[blerner]

Looking back over this issue, after having updated test feedback messages in #1350, I think our current wording is pretty good.

• I don't like "Didn't pass this is test", because the subject of the sentence is missing -- who or what didn't pass? It's not that Pyret didn't pass this test (contrast with "Pyret didn't understand your program"), and so the implicit subject of the sentence is You or Your program didn't pass the test -- i.e., it's accusative, which we're trying hard to avoid. Saying "test operator" makes the statement more neutral, accusing neither Pyret nor the programmer.

• The styling of is within "The test operator is failed..." is very subtle, unlike here on github where code has a gray background. As a result, "The is test failed" just reads clunkily to me, because it looks too much like "the is test failed", which ain't grammatical.

• We use "success!" a lot in our simulations and our talking-to-teachers, so I don't think "succeeds" is too much of a stretch any more.

• No one's complained about this in two years :)

Any further objections to the current wording, or can we close this?

[shriram]

We can close and create a new one if and when it looks problematic. Thanks.