Page MenuHomePhabricator

Provide more information about projects, etc. in tokenizer browse dialog to make distinguishing between similar projects easier
Closed, ResolvedPublic

Description

When an install has a number of similarly-named projects, it can currently be difficult to identify which project is correct (for example, if there are "Phabricator", "Phabricator Upstream" and "Upstream" projects on an install, there's no quick way to figure out what those tags are intended to convey without opening a new window and visiting the project pages separately).

We can provide more information to make this process easier in the browse dialog:

This would allow a user who wasn't sure about the difference between different projects (or wasn't sure exactly what they were looking for in general) to more quickly and confidently select the correct project by offering more on-screen context and information.

More generally, some other token types could be similarly supplemented. Function tokens and Drydock blueprint tokens might particularly benefit from greater clarity.

Vague pseudo-mock of what this might look like.

+----------------------------------------------+
| (o epriestley (Evan Priestley))   [ Select ] |
| Disabled * Admin                             |
+-                                            -+
| (m Team Rocket)                   [ Select ] |
| Blast off at the speed of light!             |
+-                                            -+
| (> libphutil)                     [ Select ] |
| Git * 2,392 Commits                          |
+----------------------------------------------+

As an alternate or supplementary approach, we could also maybe do hovercards here in some form.

Event Timeline

chad added a subscriber: chad.May 25 2016, 5:05 PM

I worry overall that this will compound the issue when installs have too many projects. That is, if they already have hundreds/thousands of projects, doubling the information makes the UI twice as large and difficult to navigate through. Maybe one idea would be to only show additional information optionally (via a checkbox) or only after results start to get filtered?

I think users are probably mostly only using this UI to browse things anyway, so it's likely OK to "slow it down" a bit visually, since that could make it easier to navigate if we save users from needing to go look up information in a new window.

I don't expect experienced users to end up here very often. If you already know what you're looking for, you probably just type it into the tokenizer 99% of the time (personally, I only use this when UI I'm testing stuff). If you don't know what you're looking for, it seems OK to me to provide more information here -- my thinking is that the typical user who ends up here is doing something like this:

  • They aren't very familiar with the install yet.
  • They know approximately what they're looking for, but not exactly what it's called.
  • They click "Browse", then type in a keyword.
  • They get, say, 5-10 choices back.

Right now, they might think that 3 of those look pretty good, but there's no way to get more information about which one they want. They'd have to open a new window and go browse to the detail pages individually, then come back to the tokenizer.

I don't really have a user in mind who is using this UI to quickly scan through >10 results and would be slowed down by having extra information. Do you run into such a use case, or have such a user in mind?

(If you have no idea what you're looking for and just click "browse" and start scrolling through all the choices in alphabetical order this is maybe worse, but I think that workflow is probably not a successful one no matter what, and likely one we can't really make successful.)

chad added a comment.May 25 2016, 5:39 PM

I can remember trying to file a bug against Safari when I worked at Apple, seems like a simple task. But typing "Safari" came back with 50-100 tags... I had no clue as a first time filer what to fill out. A short description might have helped, perhaps. But overall I guess I'd like to understand what users are ending up at the browse dialog to begin with. In the Safari case, having something like Nuance is better for the novice user than asking them to wade through 50 results and guess the correct one. I want to basically make sure we understand which user we're helping here.

The original use case on the downstream task (https://phabricator.wikimedia.org/T234) was this:

When filing a new task I entered "Ph" and the autocompletion suggested several projects. I had no clue of the difference, I chose a random one.

This seems pretty weak. You can go find the project pages to get more information, choosing a random one is obviously silly, and I think the results aren't ambiguous to reasonable users:

There are only four total active projects matching "phabricator" on the WMF install:

I think a reasonable question a user might have here is "What's the difference between Phabricator and Phabricator-Upstream? Which one should I use?". They can answer this question by navigating to the project detail pages, but they have to know that they can do this, and even if they do know it's pretty disruptive to the workflow.

This specific question is mentioned downstream, too. I don't think this is a case of having too many tasks/projects, and I think there are reasonable arguments for having separate "Phabricator" and "Phabricator-Upstream" projects in this case. Outside of this case, I think there are lots of reasonable cases where "CORGI" vs "CORGI Operations" or whatever have good reasons to be separate which may not be immediately obvious to users.

Yeah, I don't think this helps at all if there are 50 results, but I don't think we can do anything about that. Better solution is to fix the workflow somehow (nuance, subprojects, etc).

I do think it helps when there are 3 results.

Almanac Blueprints aren't mentioned downstream but I think are also a fairly good fit for this:

As are repositories, perhaps:

These workflows are a bit different, but it's pretty easy to end up with similarly-named things that aren't totally ambiguous (copies / extensions of repositories, old blueprints, out-of-date pools, etc). A quick way to get an additional line if "Main production repository." vs "Obsolete fork for ARM builds." in these cases could help prevent errors. Here, I also imagine users who are down to a list of 3-5 things and just trying to figure out which one is the one they want without needing to go pop open detail pages or look it up.

qgil added a comment.May 25 2016, 6:36 PM

You can test with "Discovery" at https://phabricator.wikimedia.org/

epriestley moved this task from Backlog to The Queue on the Prioritized board.Jun 9 2016, 7:29 PM
saggid added a subscriber: saggid.EditedJul 16 2016, 3:26 PM

Hello! What about show only active projects in "Browse projects" window?

And how about increase height size of this window? :)) People have big monitors now, as I said earlier in another task))

What about show only active projects in "Browse projects" window?

In the past, we hid disabled objects in typeaheads. Users routinely found this confusing, so I don't plan to change the behavior.

And how about increase height size of this window?

The dialog can be resized by dragging the lower right corner.

The dialog can be resized by dragging the lower right corner.

))) Many thanks. So many features hidden in Phabricator in hot keys and small elements) suprising me every day.

eadler added a project: Restricted Project.Aug 5 2016, 5:23 PM
epriestley moved this task from The Queue to Paused on the Prioritized board.Nov 10 2016, 5:49 PM
epriestley added a subscriber: scfc.

For reference, here's the current state of "discovery" downstream:

(The ordering should improve after updates pick up changes related to T8510.)

I don't think this is actually too terrible -- many of those descriptions seem relevant/useful -- although it still feels pretty under-designed to me. Obvious technical/design issues:

  • Some of the descriptions contain remarkup, but we don't render it in this context.
  • Some of the descriptions are way longer than the layout really provides room for, which looks bad and makes results hard to scan.
  • Some of the descriptions are probably too long/detailed to be useful, or otherwise don't have the right information for this context.

Some possible fixes for the remarkup issue:

  1. Render full-strength remarkup. This probably requires changing the layout to give each item much more space, because remarkup may contain block-level elements. I'm hesitant to do this and I suspect @chad is probably very hesitant to do this -- we don't really want to turn this UI into a one-result-per-page tour of every available result. Users can already use Projects to browse projects in greater detail if they're trying to get oriented, and this UI loses power for experienced users if it's a huge unscannable mess full of paragraphs of rich markup and block elements.
  2. Complete T3278: ⛄ Build a summary mode Remarkup engine for constrained text areas and render "summary" remarkup. This would render links and styles like bold, but elide or summarize block elements like tables and images.
  3. Provide an alternate, text-only field for "Project summary in typehaead results." which users only enter text into, so we don't have to worry about remarkup.
  4. Live with it.

Some possible fixes for the long descriptions:

  1. Summarize more aggressively, so we generally cut things off at the end of the first sentence instead of the end of the first paragraph.
  2. Provide an alternate, short field for "Project summary in typeahead results." which users enter dedicated text into.
  3. Live with them.

Some possible fixes for non-useful descriptions:

  1. Provide an alternate, dedicated field for a more useful description.
  2. Provide a soft hint that the first sentence of the description is a typeahead hint?
  3. Live with them.

Now that this has been deployed for a while, I'm curious if there's any feedback about it? Specifically:

  • Does this approach generally seem like it's a reasonable solution to the problem (if not in its current form, in some similar form which handles these issues more gracefully)? Or are we not really in the right ballpark?
  • How much of an issue is it that the summaries are just the first paragraphs of the project descriptions?
  • If there was a dedicated field to provide information for this view, how likely do you think it is that people would actually go fill it out?

It's also possible that we can't really get a sense of how useful this is until the rest of the ordering fixes in T8510 deploy, since searching for "discovery" (or other terms which match lots of results) don't give you the most-desirable results first right now. The process of finding what you're looking for may naturally feel more fruitful with better ordering, even without the description changes.

The downstream task (https://phabricator.wikimedia.org/T234) hasn't seen much activity and doesn't give me much insight into what the answers might be here, so I'm not sure what the state of the world is from a user perspective.

If this doesn't feel like it's a good solution, (e.g., @scfc describes this as unintuitive, downstream) we could put text into the actual results, but I think that definitely needs to come from a dedicated field so that it's short and remarkup-free in order to remain usable. That is, I don't think some hypothetical flavor of this UI is likely to be very usable, especially on mobile, and would probably be much worse for advanced users:

We can reasonably put a much shorter summary ("Sprint for Analytics Team") inline, but we can't automatically generate that information right now.

We can add a field for it, which is fairly easy, but then someone has to go fill that field out for everything, which seems like it might be hard (or, specifically, take more time than the value of this feature).

I think the answers to these questions likely inform how we move forward with this element, so I'm going to pause it for now until we have more feedback. If there's no real feedback or mixed weak opinions on things we can just call this "good enough" for the moment and find a way forward to clean up the design in the future, perhaps after T3278 gives us more options or we make other related changes in this area of the code.

chad added a comment.Nov 10 2016, 6:10 PM

Provide an alternate, text-only field for "Project summary in typehaead results." which users only enter text into, so we don't have to worry about remarkup.

(non-remarkup) Short Description is probably fine for me. Though, we should still fall back to full description if none exist.

Yeah, I think it's pretty reasonable if people would actually fill it out. We could surface it in a few other places too (e.g., /projects/) without fallback. It just seems like there's a decent chance no one will ever fill it out and it will sort of just be cluttering up the UI. But the cost on our side is pretty small, so if some people claim that they'd probably want to fill it out I'm happy to move forward with it.

chad added a comment.Nov 10 2016, 6:19 PM

We could call it "Search Description" so it feels clear that it only displays in some UIs.

chad added a comment.Nov 10 2016, 6:20 PM

Hovercards, Search, Browse, etc. It could get used.

Would you fill out at least, like, 5 of them?

chad added a comment.EditedNov 10 2016, 6:23 PM

I suppose an alternate path is to enable Dashboards on Project homepages, and you can embed your project wiki or text panel for a really cool long description and information.

I think "Search Description" only solves a narrow case where Projects are whole organizations onto themselves.


Now that this has been deployed for a while, I'm curious if there's any feedback about it? Specifically:

  • Does this approach generally seem like it's a reasonable solution to the problem (if not in its current form, in some similar form which handles these issues more gracefully)? Or are we not really in the right ballpark?

I personally think it's a good solution, however, it seems that the browse dialog isn't very discoverable currently. It takes users quite a while before they realize that this UI is even available. I'm not sure what can be done about that, however, other than making the button stand out better (make it uglier?)

  • How much of an issue is it that the summaries are just the first paragraphs of the project descriptions?

The first paragraph might be fine. It feels a little busy to me and maybe a shorter summary would be better, however, that requires people to be extra thoughtful in writing descriptions to make them most useful. Still, at least in the Wikimedia community, I would expect people to be familiar with this sort of thing.

  • If there was a dedicated field to provide information for this view, how likely do you think it is that people would actually go fill it out?

This seems like a lot of extra work with minimal benefit, IMO. If the edit form warns people that the description is summarized in various UIs then they can be thoughtful and write the first part of the description in a way that works.


With all of that said, I really feel like cutting it off at the first sentence might be fine and that would make the list a lot less busy-looking.

+1 to what 20after4 wrote. The approach is definitely helpful, and to make this look less cluttered and inconsistent ("are projects with longer descriptions which take up more vertical space somehow more important?"), cutting off project descriptions seems like a good compromise.

Alright, I'm going to try this:

  • Produce shorter summaries (roughly the first sentence, instead of roughly the first paragraph).
  • Try adding an optional "Search Description" (maybe "Usage Hint"?) field which is used instead, if populated, and see how much complexity/mess that adds.
  • Make the icon extremely ugly with an aggressive animation, vibrant flashing colors, and a periodic alert sound.

Okay well @chad resigned from D16893 as soon as he saw animation in a CSS file so I don't think that one's going anywhere.

chad added a comment.Nov 17 2016, 9:08 PM

I should make a Herald rule to auto-resign.

(You could write some similar rules if you want to try something in that vein, although it's a pretty big pain to fork JS/CSS right now.)

This is sort of what I was thinking about for the "Search Description" / "Usage Hint" (descriptions / projects are random examples):

After playing with it a little bit I don't feel too great about how it looks -- I think it adds a lot of visual clutter even in the best case where I've written particularly simple/meaningful hints. I think there's also no way we have space for it on mobile without breaking each option across multiple lines. The naive approach looks like this, which is obviously pretty garbage:

We could clean that up, but it means that part of the control will often scroll off the page, so you have fewer options to choose from, especially with the software keyboard active. Here, I can only directly select from 3 options, while I'd have 5 without the extra hints:

This is generally feeling like a direction that helps new users a little bit but hurts and annoys experienced users to me.

chad added a comment.Nov 18 2016, 4:59 PM

The main concern for me would be typeaheads are for knowing what you're looking for already, and making that faster / easier. Browse interfaces are for discovery.

I'd probably want to take a step back and understand what the root problem here is, what information people are looking for, and can we maybe through Nuance or Custom Forms, find a way to eliminate this need. I'd even be curious if we could somehow tie Custom Forms into reduced typeaheads. For example, you make a custom form for a top level project (wikidata), have the project typeahead return only results that wikidata supports.

Just spitballing.

Yeah, I tend to agree. I don't really see any approaches we can take here that don't make things a little worse for experienced users who already know what they're looking for, and I'm not sure there's too much of a use case left for less-experienced users.

I think the feature as it exists today does a reasonable job of helping semi-experienced users select between multiple different similar tags in an area they aren't closely familiar with. If you know roughly what you're looking for but aren't exactly sure, you can hit the button to quickly get some extra information that distinguishes between #thing-management and #thing-operations or whatever.

If you have no idea what you're looking for the feature isn't particularly helpful, but I don't think this is really a problem we can solve this way. The original downstream task discusses typing "ph" and not knowing which result to pick. But, broadly, I don't think we ever expect new users to figure out how to file bugs by guessing randomly, looking through all of the results, and selecting the correct ones. Most kinds of tags can't ever be discovered this way since a new user will not know that they exist or what they're searching for. Examples on this install are Bug Report, Feature Request, and Contributor Onboarding: if we expected users to use the typeahead to find and correctly tag new tasks with those tags, I expect almost none would succeed. From quickly checking, it looks like WMF has similar tags like #easy, #needs-volunteer, etc.

If there's some remaining use case here, I'd also like to step back and understand it better since I suspect the best solution we can pursue is not any kind of UI change which makes it easier to find things by randomly typing guesses into the typeahead.

For example, if there's some set of common tags that a lot of tasks should be getting tagged with when they're created, but they aren't being tagged because newer users don't know they exist, maybe the help text above the form could include (or link to) a table describing those tags?

This is obviously a little absurd as a parallel, but if you aren't sure who security bugs should be assigned to you wouldn't go through a process like this:

  • Remember that you met someone who works in Security named Chris -- or maybe Karen? Something like that, anyway. He or she seemed very helpful.
  • Type "c" into the "Assigned To:" typeahead.
  • Expect that the correct assignee will be easy to find from there.

If there's some remaining use case here, I'd also like to step back and understand it better since I suspect the best solution we can pursue is not any kind of UI change which makes it easier to find things by randomly typing guesses into the typeahead.

I propose to close this task as resolved (as usual, thanks for the constructive discussion and iterations on approaches!).
A month ago I asked for feedback in downstream regarding the current implementation. I did not receive any.
I'm happy with the current implementation (search dialog offering an excerpt of project descriptions), and it's up to us in downstream to teach users about clicking the project search.

If there are further use cases they should be filed as separate tasks.

epriestley closed this task as Resolved.Mar 16 2017, 2:09 PM
epriestley claimed this task.

That sounds reasonable to me. We remain open to more feedback here if it does turn up, but I think we don't have a clear set of next steps otherwise. Thanks for following up!