Improve inline documentation for magnifier toggle feature
ClosedPublic

Authored by ngraham on Jul 17 2018, 6:43 PM.

Details

Summary

The inline documentation for the magnifier feature is slightly confusing in a way that could frustrate users: since it's not mentioned that holding down only toggles the magnifier while resizing the selection rectangle, there's the very likely potential for the user to hit during another time, notice that nothing has happened, and conclude that the feature is broken.

This patch improves the documentation to make it clear under what circumstances holding down the key will do something.

Test Plan

Diff Detail

Repository
R166 Spectacle
Branch
magnifier-inline-documentation-text (branched from master)
Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 1017
Build 1030: arc lint + arc unit
ngraham requested review of this revision.Jul 17 2018, 6:43 PM
ngraham created this revision.
ngraham edited the summary of this revision. (Show Details)Jul 17 2018, 6:44 PM
ngraham edited the test plan for this revision. (Show Details)
ngraham edited the summary of this revision. (Show Details)
rkflx requested changes to this revision.Jul 17 2018, 11:52 PM
rkflx added a subscriber: rkflx.

Good idea, but IMO your proposed wording is worse than before.

src/QuickEditor/EditorRoot.qml
306

Hmh, what do you mean by "dragging"? Isn't this when you move the complete rectangle, without changing its size?

If so, that would be even more misleading, as the magnifier won't be shown then at all. How about this:

while dragging resize handles

…or simply

while resizing selection
306

Indentation is off by one space ;)

This revision now requires changes to proceed.Jul 17 2018, 11:52 PM

Heh, each of our preferred wordings reveals our workflow: I always drag a new selection rectangle, so to me, "dragging" makes sense as a description of how it's used. But as I recall now, you prefer to have Spectacle remember the previous selection, and you resize it from one of the handles, so "resizing" is the word that best describes how you use it. It seems we need to think of a string that adequately describes both use cases...

Heh, each of our preferred wordings reveals our workflow: I always drag a new selection rectangle, so to me, "dragging" makes sense as a description of how it's used.

https://en.wiktionary.org/wiki/drag#Verb has this:

(computing) To move (an item) on the computer display by means of a mouse or other input device. "Drag the file into the window to open it."

In this case what you move (i.e. "drag") is the cursor, or one of the handles by extension. The moved item is certainly not the selection rectangle, because it stays stationary and only changes its size.

Thus I think what you mean is "drawing". "Dragging [the] selection rectangle" is not accurate in my book. "Drawing" is also the terminology used in the help text before you perform the initial click.

But as I recall now, you prefer to have Spectacle remember the previous selection, and you resize it from one of the handles, so "resizing" is the word that best describes how you use it.

No, this is not about me. This is about the common workflow of first drawing an approximate rectangle, and then adjusting it afterwards.

It seems we need to think of a string that adequately describes both use cases...

"Resizing selection" is also an accurate description of what you do initially, not sure what's the problem with that?

To me, "Resizing selection" communicates modifying something that already exists, not creating it anew. Also, it wouldn't be accurate now that we have the keyboard manipulation feature merged, because it's now possible to resize the selection with the keyboard and not see the magnifier.

"Hold to toggle magnifier while drawing selection rectangle" is something I could get behind.

rkflx added a comment.Jul 19 2018, 6:34 PM

"Hold to toggle magnifier while drawing selection rectangle" is something I could get behind.

Yes, drawing is what you do initially. But after you are done drawing, you are moving and/or resizing, i.e. modifying.

How about "changing"?

(I guess there was a reason why I went with the original wording, which you approved BTW.)

"Changing" also seems to cover the case of using the new keyboard shortcuts to modify the selection rectangle, even though it won't actually appear while doing so.

The original reason why I liked "Dragging" is because it implies mouse movement, which is the only circumstance in which the magnifier can appear. Basically I'd like to communicate that the magnifier toggle only works when you're using the mouse to initially draw or later modify the selection rectangle.

rkflx added a comment.EditedJul 19 2018, 6:58 PM

It's probably impossible to specify the exact conditions the magnifier appears in, unless you put tens of lines of code into writing. Therefore we have to find the most accurate compromise.

Since initially drawing the selection and afterwards using the mouse to modify it are the most common scenarios, the text should adapt to those. Also, for keyboard navigation (which I'd assume is a rather minor use case) the meaning of Shift is redefined in the text, so I don't think it would be that confusing.

My vote is for "resizing" ("changing" also applies to "moving", where the modifier does not appear).

Related: As we have "Reset selection" (without "rectangle"), we should drop "rectangle" here too.


We could also go back to another idea from above: "while dragging selection handles", or simply "while dragging cursor".

It's probably impossible to specify the exact conditions the magnifier appears in, unless you put tens of lines of code into writing. Therefore we have to find the most accurate compromise.

Since initially drawing the selection and afterwards using the mouse to modify it are the most common scenarios, the text should adapt to those. Also, for keyboard navigation (which I'd assume is a rather minor use case) the meaning of Shift is redefined in the text, so I don't think it would be that confusing.

Makes sense to me. This implies that we should choose a phrasing that's mouse-specific, which is why I liked the word "dragging." However, "while dragging selection handles" seems overly technical to me. I don't know about in other languages, but "while dragging selection box" is pretty common and well understood in English.

I could accept "while dragging selection handles" as a compromise though.

rkflx added a comment.Jul 19 2018, 7:33 PM

"while dragging selection box" is pretty common and well understood in English.

You are dragging "something", and as I tried to point out above, that "something" is not the rectangle, box or whatever you call it. The rectangle stays stationary, and only changes its size. What you are dragging is the physical mouse, the cursor on the screen, and the selection handle under it (along with the edges attached to it, but not all edges and thus not the complete box).

I could accept "while dragging selection handles" as a compromise though.

Okay, great.

"while dragging selection box" is pretty common and well understood in English.

You are dragging "something", and as I tried to point out above, that "something" is not the rectangle, box or whatever you call it. The rectangle stays stationary, and only changes its size. What you are dragging is the physical mouse, the cursor on the screen, and the selection handle under it (along with the edges attached to it, but not all edges and thus not the complete box).

Just to make myself clear here, I understand your perspective, and you are correct from both a technical and a grammatical point of view. However what I am attempting to communicate is that the phraseology "drag a box", while technically and grammatically questionable, are instantly comprehensible English-speaking computer users (not sure about other languages). If you tell an English-speaking computer user to, for example, "drag a box around those icons," they will be able to do it even though your request may not have won any awards in grammar school. :)

All that said, I accept the compromise phrasing. But I don't want you to think I have no command of the grammar of my own native language. :)

ngraham edited the test plan for this revision. (Show Details)Jul 19 2018, 8:20 PM
ngraham updated this revision to Diff 38101.Jul 19 2018, 8:21 PM

Update the string

rkflx added a comment.Jul 19 2018, 8:22 PM

Thanks, commit it already ;)

If you tell an English-speaking computer user to, for example, "drag a box around those icons," they will be able to do it even though your request may not have won any awards in grammar school. :)

That's probably what will happen if you say "around those icons", but what will happen if you fire up Impress, draw a rectangle, and instruct users to drag the box? I bet they will move it, not draw a new box or resize the old box. It's also important to be accurate in English, because every translation will be done based on that, with only the string and no further context available to the translators.

All that said, I accept the compromise phrasing. But I don't want you to think I have no command of the grammar of my own native language. :)

I'm not thinking that, and I hope you don't read that from my comments. And BTW, if you notice any regular mistakes or idiosyncrasies in my writing, kindly let me know when possible. I'm always interested in improving…

rkflx accepted this revision.Jul 19 2018, 8:22 PM
This revision is now accepted and ready to land.Jul 19 2018, 8:22 PM
ngraham closed this revision.Jul 19 2018, 8:57 PM
rkflx added a comment.Jul 19 2018, 9:08 PM

Is there something wrong with our Git branch setup for KDE Applications? Today Scott, Peter and you all had problems with merging stable into master…

Or maybe there's something wrong with us, or maybe git is just obtuse and it takes 10 years of constant use to avoid making silly mistakes with it. :)

Here's the sequence of events for me when I want to land D14196:

Realizing that I had originally branched from master rather than Applications/18.08, I decided to cherry-pick the commit onto Applications/18.08 and close the revision manually rather than re-base it and land using arc. This worked fine.

Then I switched back to master and did the merge. However, I had forgotten to update it first, so I was merging onto yesterday's master, and there were merge conflicts. I fixed the merge conflicts and committed the result. When I tried to push, it rejected the push because origin/master had work I didn't have, so I did a git pull --rebase to update my local branch while preserving the changes. This worked. But it had the side effect of erasing the merge commit, so when I pushed, it duplicated my patch commit rather than making it look like a merge.

rkflx added a comment.Jul 19 2018, 9:23 PM

Thanks for the explanation.

Or maybe there's something wrong with us, or maybe git is just obtuse and it takes 10 years of constant use to avoid making silly mistakes with it. :)

The trick is to check your work before offering it to the public. (Works for more than commits.)