discoverability improvements #1704

annthurium · 2018-09-25T23:06:17Z

Description of the Change

There are a lot more Atom users than there are users of the Git/Github package. This points to a discoverability problem. There are menus and commands to open the Git/GitHub panes, but in order to do that you have to know the panes exist.

This pull request changes the icon and text in the status bar to say "Git (n)" where n is the number of changed files, and the icon is a diff icon. This pull request also adds a GitHub icon and text to the status bar, which toggles the GitHub tab when clicked.

Alternate Designs

I thought about not showing the GitHub status bar icon if there are no GitHub.com remotes present. The GitHub tab isn't very useful in that case. It's not really doing any harm to show the GitHub tab -- it's just not a great use of real estate. Thus, I decided the complexity of hiding the icon wasn't worth the hassle.

Benefits

Hopefully, more users will learn that the git and github panes exist, use them, and find the meaning that's been missing from their lives.

We plan on doing usability testing to validate the assumption that the UI improves discoverability.

Possible Drawbacks

If we keep adding stuff to the status bar, eventually it's going to get too crowded. For right now, it's fine.

Applicable Issues

#1573

Metrics

When a user clicks on the GitHub status bar icon, we record an event.

Tests

Unit tests to validate that...

ChangedFilesCountView:
renders the new icon
renders the text "Git"
GithubTileView:
- renders the new icon
- renders the text "GitHub"
- records an event when clicked
- calls the passed in prop when clicked
StatusBarTileController:
- toggles the GitHub tab when clicked

Manual testing to validate that...

the git tab shows / hides when the status bar icon is clicked
the github tab shows / hides when the status bar icon is clicked
clicking the github tab doesn't cause any errors if no github.com remotes are present.

lib/controllers/status-bar-tile-controller.js

coveralls · 2018-09-25T23:16:37Z

Coverage decreased (-0.05%) to 81.946% when pulling 6a49d36 on tt-18-sept-discoverability into 1b4c899 on master.

kuychaco

Excited for this! Hopefully it helps a lot with discoverability. Thanks for spearheading these efforts @annthurium!

kuychaco · 2018-09-26T00:29:14Z

lib/controllers/status-bar-tile-controller.js

@@ -5,6 +5,7 @@ import BranchView from '../views/branch-view';
 import BranchMenuView from '../views/branch-menu-view';
 import PushPullView from '../views/push-pull-view';
 import ChangedFilesCountView from '../views/changed-files-count-view';
+import GithubStatusBarTile from '../views/github-status-bar-tile';


Here's a suggestion for the class name based on package convention (ending with the word "view") and context (being in the status-bar-tile-controller.js file) -- GitHubTileView. And the file could be github-tile-view.js.

Similarly, since you changed the tile for opening the Git panel it might be more appropriately named something like GitTileView and the file git-tile-view.js.

Corresponding test files would need to be changed accordingly.

good call! I'll change the name.

kuychaco · 2018-09-26T00:35:32Z

lib/views/changed-files-count-view.js

-        <Octicon icon="diff" />
-        {label}
+        <Octicon icon="git-commit" />
+        {`Git (${this.props.changedFilesCount})`}


This pull request changes the icon and text in the status bar to say "Git (n)" where n is the number of changed files

Interestingly, when I first saw this my initial thought was that n was the number of git commits... I notice currently we have the number as well as the word "Files" which makes it very clear that the number refers to the changed file count. I wonder if there's a way we could make it more clear with your new version... adding the word "Files" might take up too much space. I think it would even be fine to just drop the file count...

@simurai do you have 💭s?

I think it would even be fine to just drop the file count...

That would be the least confusing, but we'd miss out on informing the user that there are uncommitted changes, which might be important information to keep.

adding the word "Files" might take up too much space.

Hmm.. yeah.

Or how do you like some sort of "notification badge":

Atom IDE uses something similar. It could also be just grey to be a bit more subtle.

Good points, you two! Some thoughts...

Anecdotal data point: I showed my partner the new interface and asked what he thought Git (2) referred to. He correctly guessed "the number of uncommitted changes I have made." I asked if having that information at a glance would be useful, and he said yes. When I showed him the old interface, he was not sure what the 2 files referred to.

I like the bright color on the badge and think it might encourage users to click, but if the goal is to clarify what "2" refers to it doesn't help.

I'd like to ask users about this in the context of an actual research session and let that inform the road we choose to take. If they don't know what the changed file count refers to but would find that information useful, we can add the word "files" back in. It's slightly crowded but not horrible. If they wouldn't find that information useful, we can drop it entirely. Sound good?

Sounds good to me! Would we do this UXR prior to merging? Or just prior to releasing?

Edit: I see that your intention is to merge soon, so the answer is not prior to merging. I'm totally cool with that. Just curious what our plan would be for doing this research before shipping.

good question. my intention is to do research before next release, with enough time to make additional changes if necessary. Since we have a month before next release I think that's do-able. I finished the uxr script just now, so next I'll focus on rounding up some users.

kuychaco · 2018-09-26T00:39:07Z

lib/views/github-status-bar-tile.js

+  }
+
+  handleClick() {
+    addEvent('click', {package: 'github', component: 'GithubStatusBarTile'});


Not sure what convention we're going with for event names (or if we have even discussed one yet)... I had the thought that a more descriptive event name could be handy, something like toggle-github-tab. That way whoever is combing through the data we're collecting can more easily infer what the events are for in terms of extracting information about user behavior.

That said, I can also see the value in simply stating that we're capturing a click event on a particular view element...

Oh okay, so we want to decouple the UI action (click on an element) from the effect of the action (toggling the tab). We've instrumented the reveal and hide methods of the TabTracker which tells us the number of times a given tab is opened/closed. We also want to know what method was used to reveal/hide the tab, which is what we're doing here. Does that sounds about right?

we already record an event for toggling the git and github tabs, in the RootController. 😸

This additional event allows us to know that the button is clicked. If the tabs are toggled a lot, but these buttons are never clicked, we have an additional data point to know that these buttons aren't helping users discover the tabs.

kuychaco · 2018-09-26T00:45:04Z

lib/views/github-status-bar-tile.js

+      <button
+        className="github-StatusBarTile inline-block"
+        onClick={this.handleClick}>
+        <Octicon icon="mark-github" />


simurai · 2018-09-26T05:08:46Z

lib/controllers/status-bar-tile-controller.js

@@ -88,6 +94,7 @@ export default class StatusBarTileController extends React.Component {
    return (
      <Fragment>
        {this.renderTiles(repoProps)}
+        <GithubStatusBarTile didClick={this.props.toggleGithubTab} />


How about moving the GitHub tile to the far right?

Then it's more in order of this typical 🤔 workflow:

Choose a branch

Make sure it's up-to-date

Make changes

Create PR

@simurai if we move the GitHub tile to the far right, we run the risk of disrupting flows for users who have grown accustomed to "click on the thing on the far right" to open the Git pane.

Then again, this would force those users to discover the GitHub pane. 😆

@annthurium That's a good point, although the "far right" sometimes gets used by the "updates" and "blue squirrel".

Another option would be to move "GitHub" to the left, before the branch name:

Just so that "GitHub" doesn't get sandwiched between the Git "actions" and the Git tab.

annthurium · 2018-09-27T18:17:58Z

@simurai @kuychaco I'm going to merge this, as I believe I have addressed all feedback. I am super open to addressing additional concerns in the future, if you have any.

bmario · 2018-11-29T15:09:02Z

lib/views/changed-files-count-view.js

    return (
      <button
        ref="changedFiles"
        className="github-ChangedFilesCount inline-block"
        onClick={this.handleClick}>
-        <Octicon icon="diff" />
-        {label}
+        <Octicon icon="git-commit" />


I think changing the icon from diff to git-commit isn't a good choice. The pane is about changed files, it tells you how many files have local changes, yet it uses the symbol for commits. When I first saw the new layout, I'd expected to get the equivalent of git log and were confused about what the number is going to tell me.

The Git panel includes different things:

Changes

Commit message editor

Recent commits

The "Recent commits" is some sort of mini git log:

So it doesn't seem easy to find a good icon that fits everything. Using the git icon should hint at: "Create and view commits".

I'd agree, that for the pane the git commit icon is a better fit, but I'm talking about the status bar button.

The issue is, you're optimizing this for people who aren't even using it. And in doing so, you are breaking the current UI for the users you already have. You shouldn't take that lightly. The new layout doesn't convey more information, nor does it free up precious space in the status bar. Once you found out that the Git(Hub) pane exists and that the buttons will open those panes, these buttons take up space because they got bulky.

I agree that the "n files" label wasn't perfect. What I'd suggest is merely splitting up the buttons. Make one button with just the diff icon and the number of changed files as the label. And a second button with the git-commit icon and git as its label. Both buttons open the diff/commit git pane on click, but the information is logically split. Plus, users who already discovered the git pane can hide the git button without losing functionality. Additionally, all buttons should have a tooltip like every other thing in the status bar does.
I'd even make a PR for that if you like that idea.

nor does it free up precious space in the status bar.
What I'd suggest is merely splitting up the buttons. Make one button with just the diff icon and the number of changed files as the label. And a second button with the git-commit icon and git as its label.

Here a mockup:

But wouldn't two buttons take up even more space than just a single button?

Also since the two buttons do the same thing, could that be confusing? People would click on both and then think something must be broken since in both cases it opens the same panel. Maybe this could be made less confusing if the focus moves to the changes and the recent commits. Like this:

But having the focus in two different places seems less useful for users that use the mouse to open the git panel.

Tilde Ann Thurium added 5 commits September 25, 2018 14:31

change git status bar icon/text

20cdf5d

add GitHub icon to status bar

ea195cf

fix ChangedFileCountView tests

6915b89

add test for toggling github status bar tile

f810ed0

add tests for GithubStatusBarTile

926b033

annthurium commented Sep 25, 2018

View reviewed changes

lib/controllers/status-bar-tile-controller.js Show resolved Hide resolved

kuychaco reviewed Sep 26, 2018

View reviewed changes

simurai reviewed Sep 26, 2018

View reviewed changes

GithubStatusBarTile => GithubTileView

6a49d36

annthurium mentioned this pull request Sep 26, 2018

unused prop in StatusBarTileController #1705

Closed

annthurium merged commit 157c5a8 into master Sep 27, 2018

annthurium deleted the tt-18-sept-discoverability branch September 27, 2018 18:18

annthurium mentioned this pull request Sep 27, 2018

open Git pane when merge conflicts are present #1709

Merged

annthurium mentioned this pull request Oct 20, 2018

v0.21.0-0 QA Review #1752

Closed

7 tasks

bmario reviewed Nov 29, 2018

View reviewed changes

withinfocus mentioned this pull request Nov 29, 2018

Hide GitHub in status bar when not relevant #1815

Closed

discoverability improvements #1704

discoverability improvements #1704

annthurium commented Sep 25, 2018 •

edited

coveralls commented Sep 25, 2018 •

edited

kuychaco left a comment

kuychaco Sep 26, 2018

annthurium Sep 26, 2018

kuychaco Sep 26, 2018

simurai Sep 26, 2018

annthurium Sep 26, 2018

kuychaco Sep 27, 2018 •

edited

annthurium Sep 27, 2018

kuychaco Sep 26, 2018

kuychaco Sep 26, 2018

annthurium Sep 26, 2018

kuychaco Sep 26, 2018

simurai Sep 26, 2018

annthurium Sep 26, 2018

simurai Oct 1, 2018

annthurium commented Sep 27, 2018

bmario Nov 29, 2018

simurai Nov 30, 2018

bmario Dec 6, 2018

simurai Dec 10, 2018

discoverability improvements #1704

discoverability improvements #1704

Conversation

annthurium commented Sep 25, 2018 • edited

Description of the Change

Alternate Designs

Benefits

Possible Drawbacks

Applicable Issues

Metrics

Tests

coveralls commented Sep 25, 2018 • edited

kuychaco left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kuychaco Sep 27, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annthurium commented Sep 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annthurium commented Sep 25, 2018 •

edited

coveralls commented Sep 25, 2018 •

edited

kuychaco Sep 27, 2018 •

edited