Service desk should be given more prominence in the UI

Description

The Service Desk is a valuable but underused feature. This is, in part, because it is not necessarily a feature our users are aware of or fully understand.

Proposal

In order to make this feature more visible, it should be given its own UI underneath Issues and its own link in the sidebar.

1. In the first iteration, when you click on the Service desk link in the navigation, it goes to a version of the issues page, with the author filter set to the GitLab Support Bot. It defaults to the open tab. So it will show all open Service desk issues. This is a special version of the issues page because the search filter is locked to filtering the author to the GitLab Support Bot. However, you can search/filter by other elements. Just the author filter is locked.

2. Be sure to remove the x in the author filter, since it's locked. Also, you cannot remove the author filter with any other interaction. You can't backspace/delete it with your keyboard.

3. There is some explanatory text at the top of the page, with a mailto link, a link to project settings, and a link to the Service desk docs.

Design

• Copy:

**Use Service desk to connect with your users (e.g. to offer customer support) through email right inside GitLab.** 
Have your users email incoming+victorwu/acme-lawncare-ios@gitlab.com. Those emails automatically become 
issues (with the comments becoming the email conversation) listed here. [Read more]

GitLab issue tracker on

• Show Service desk navigation element. Also:

	SD off	SD on
Non-empty state (i.e. At least one result in search+filters)
Empty state (i.e no results in search+filters)

GitLab issue tracker off

• Do not show Service desk navigation element.

SVG: graphic-service-desk.svg

Documentation blurb

Overview

Giving Service desk a dedicated space in the UI will increase awareness while making it easier for users to take full advantage of this feature. GitLab admins will see a clear path to creating a support workflow.

Use cases

Link to Service desk details: https://docs.gitlab.com/ee/user/project/service_desk.html

Feature checklist

Make sure these are completed before closing the issue, with a link to the relevant commit.

• Feature assurance
• Documentation
• Added to features.yml

marked this issue as related to gitlab-ee#3034

marked this issue as related to gitlab-ee#3035

Issue based on our conversation last Friday @victorwu @JobV. @hazelyang, would love for you to assist in creating the empty state banner for this feature's page.

changed the description

added gitlab-ce~2024184 label

added gitlab-ce~2278651 label

added EE Premium label

would love for you to assist in creating the empty state banner for this feature's page.

@sarrahvesselov Will do!

marked this issue as related to #3034

marked this issue as related to #3035

marked this issue as related to #3054 (closed)

marked this issue as related to #2735 (closed)

changed the description

@sarrahvesselov : I updated your description a little bit. I think it's what you are thinking about, but more correct.

When an external user sends an email to the service desk email, GitLab creates a service desk issue. The way the system knows it's a service desk issue is the fact that the author of the issue is a special user called GitLab Support Bot. So I think the easiest way for that page to work is that it's really the same page as the issue page, but that the search bar is preconfigured.

And so we shouldn't have a "banner" and we don't need to do any banner dismissing logic. We can simply have a specialized empty state message whenever a user searches for the GitLab Support Bot authored users.

@hazelyang : Let me know if you have any better ideas. Hazel worked on originally designing Service desk with the support bot concept and all. So she should have some good ideas too.

mentioned in issue #2735 (closed)

I updated your description a little bit. I think it's what you are thinking about, but more correct.

Thanks. From our conversation Friday, I was under the impression it would be its own page. As a first iteration, this is fine.

And so we shouldn't have a "banner" and we don't need to do any banner dismissing logic.

Sounds fine.

@sarrahvesselov : My assumption is that it should be a simple re-direct to the issues page with the search bar filled in. But I'm open to other ideas. I think an alternative design which I guess would be similar effort is that you see the issue page, but the search bar is locked to only filtering on the GitLab support bot user. Thoughts?

the search bar is locked to only filtering on the GitLab support bot user

This is more in line with what I took away from the conversation @victorwu. I can see users changing labels on the screen without understanding that they are actually interacting with the generic issues list. They would very quickly be looking at non-bot issues without realizing it. Locking it to only support bot issues will keep the UX more predictable.

changed the description

Thanks @sarrahvesselov . I like that idea. By locking it also teaches users what that filter means. I've updated the description accordingly.

changed the description

changed the description

mentioned in issue #3054 (closed)

added frontend label

added Deliverable label

@victorwu do you think that is sufficient in teaching how service desk works? I'd love it if we could make it even more obvious. Be that a line somewhere You're only viewing Service Desk issues or by having the filter show Type: Service Desk instead, for example.

@JobV : I originally thought of including some explanatory text in the empty state. But that's not really helpful for new users if there's already one service desk issue.

I updated the mockup in the description. I think we can simply have some explanatory text always there, and link to docs, config, and display the mailto link of the email address that external users use.

For the filter itself, I don't think it's worth it (for now at least), to use a special filter (since that will incur extra work). Right now, the nav (and breadcrumbs) makes it obvious that this page is for Service desk. So when they arrive at the page, they already know the context. And then we provide them a little of explanatory text. So even if they don't understand that special locked filter, it's still okay. Because they just need to know to navigate to this special page.

changed the description

I think we can simply have some explanatory text always there, and link to docs, config, and display the mailto link of the email address that external users use.

I agree with you @victorwu, I think this should be sufficient for the first iteration.

assigned to @hazelyang

assigned to @victorwu

@sarrahvesselov : I see you asked @hazelyang for some designs here earlier. @hazelyang : Could you look at the discussion so far and give a final design? Thanks!

I think the explanatory text on the top of issues list looks more natural than at the top of the page, so I moved it.

@hazelyang : That looks great! Can you please update the description and attach the asset.

changed the description

Updated the description!

added UX ready and removed UX labels

changed the description

mentioned in commit gitlab-design@b8d49884

assigned to @brycepj

@brycepj let me know when you're close to completion with this as I will need to integrate with it for https://gitlab.com/gitlab-org/gitlab-ee/issues/3054

@ClemMakesApps OK -- just FYI, I haven't started yet.

@ClemMakesApps : Should we cut scope for #3054 (closed) then?

@victorwu, afaik, Service Desk doesn't show up on the nav sidebar until this Deliverable is completed. I can still do #3054 (closed), I just can't add the service desk tooltip until the service desk shows up on the side.

@victorwu @sarrahvesselov Currently in filtered search, you can use the "Delete" key to remove an author. You've discussed above removing the X, but I'm assuming we want to prevent it being deleted as well?

created branch 3049-service-desk-should-be-given-more-prominence-in-the-ui

mentioned in merge request !2733 (merged)

@brycepj : You mean like "backspace" for a windows machine?

Yeah, we shouldn't be able to allow a user to remove that filter. Currently, the same implementation is in the issue board when you have a board milestone. There's no x and you can't backspace it away. (I just checked.) Let me update the description here to make that clear.

changed the description

@victorwu Thanks -- I didn't realize we'd already implemented this with boards. That will likely (I think) make this quite a bit easier.

mentioned in issue #3212

@smcgivern I think this will at least need a route set up -- can you foresee any other backend work?

@brycepj I think that's probably it. I don't have anyone available right now, but I can help. Please ping me on the MR / Slack with what you need, and I'll add it

@victorwu @sarrahvesselov What does the empty state look like here? I'm assuming we don't want to show the same empty state we show for the issues page. Maybe the documentation box we have will be enough?

@brycepj : Are you referring to this?

I thought we would just get that by default. I think that's okay. Because indeed there's no issues to show. And as you mentioned, the doc box is already there. So I think that's fine. The "Email a new issue to this project" link is a bit weird. Could we take that out if it doesn't make the code too messy / not clean?

@smcgivern : I noticed that our gitlab support bot on .com doesn't have the correct avatar. Are we able to ship the correct avatar in the code / seed data? We probably missed it in an earlier issue. Create a new issue?

I thought we would just get that by default. I think that's okay. Because indeed there's no issues to show. And as you mentioned, the doc box is already there. So I think that's fine. The "Email a new issue to this project" link is a bit weird. Could we take that out if it doesn't make the code too messy / not clean?

It will most likely be empty for most people when they click on this feature for the first time. Therefore, shouldn't they see the explanatory text @hazelyang designed @victorwu?

Are you referring to this?

@victorwu Yeah, that's what I meant. I was thinking along the same lines as @sarrahvesselov -- that we'd want to display something more helpful.

In the case where the user's not new (they've hidden the doc box) and there are no issues (this is probably not uncommon, if they're trying to stay on top of support requests), we'll need to show something.

I think the existing generic issues empty state would work in that case -- I had forgotten we can hide the "New Issue" button there.

But then we need to consider again the case when the user is new (doc box not hidden) and there are no issues. Is it okay to stack the doc box and the empty state graphic on top of each other?

The "Email a new issue to this project" link is a bit weird. Could we take that out if it doesn't make the code too messy / not clean?

I thought we would just get that by default.

@victorwu, with most of these things, we do get them more or less 'for free', but they're also pretty easy to remove/add. So these decisions shouldn't affect the time to implement this.

In the case where the user's not new (they've hidden the doc box) and there are no issues (this is probably not uncommon, if they're trying to stay on top of support requests), we'll need to show something.

Users cannot dismiss this doc box according to @victorwu here https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_36566100.

But then we need to consider again the case when the user is new (doc box not hidden) and there are no issues. Is it okay to stack the doc box and the empty state graphic on top of each other?

I believe the empty state should contain the same info as the doc box, doc box removed. The doc box should only appear when there are issues present. In the future, I believe we should make it dismissible per user.

@brycepj : As @sarrahvesselov said, the doc box is not a dismissible banner, in the style of our other banners. If you look at the description / mockups, it's part of the persistent UI itself.

What do you think @hazelyang?

As @sarrahvesselov said, the doc box is not a dismissible banner, in the style of our other banners. If you look at the description / mockups, it's part of the persistent UI itself.

Oops -- I missed that.

I believe the empty state should contain the same info as the doc box, doc box removed. The doc box should only appear when there are issues present. In the future, I believe we should make it dismissible per user.

Agree with @sarrahvesselov.

Empty state

SVG:graphic-service-desk-for-empty-state.svg

@victorwu please create a separate issue! It doesn't look like we provide an avatar for the ghost user either: https://gitlab.com/ghost1

added In review label

@victorwu It's not explicit in the description, but I'm assuming we want to support bulk updating, exporting, and subscribing to service desk issues?

@brycepj : No, let's leave all those out. Sorry for not being more clear, and I see it's in the description mockup.

Unless it's extra work not to include those, let's leave all that out. Let me know what's easiest and I'll update the description (and mockup accordingly).

@victorwu okay -- it would require extra work for all three, respectively, but at first glance, probably not much. I'd say if there's customer interest in any or all of them, it'd be reasonably easy to integrate in the future.

@smcgivern @hazelyang @smcgivern @sarrahvesselov :

Forgot to separate out into different cases. My bad. My proposal:

Service desk is turned on

• Show the navigation element in the menu.
• The list view of issues in https://gitlab.com/gitlab-org/gitlab-ee/uploads/77383557deac8ded7a0f14ed36e38a3b/service-desk.png should behave normally. It doesn't depend on whether service desk is on or off right?
• The help text is as per the mockup, and there is an email address.
• I think we should remove the Configure service desk button. Users can go to the settings and do it themselves by reading the docs.

Service desk is turned off.

• Show the navigation element in the menu.
• The list view of issues in https://gitlab.com/gitlab-org/gitlab-ee/uploads/77383557deac8ded7a0f14ed36e38a3b/service-desk.png should behave normally, same as above.
• Update the help text in the mockup to remove the sentence regarding the specific email address (because it's not live currently).
• Change the button in the mockup to say Turn on Service desk (which should redirect to the settings page).

Are you folks agree with the above proposal? Let's finalize the design here first, and then consider what we can squeeze in our remaining time. (We can create separate issues if necessary.)

changed the description

Thanks @brycepj : I updated the description mockup to make it clear those features (https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_38820251) are not in scope.

It doesn't depend on whether service desk is on or off right?

If Service Desk is turned off, then no issues will show. The view would then be this, correct @victorwu? https://gitlab.com/gitlab-org/gitlab-ee/uploads/60bb7db3274bc9e5eccd7a6ff16262c7/service-desk-empty.png

@sarrahvesselov : Turning on/off Service Desk only enables/disables external people to/from sending in emails to that special email address (and thus creating those issues). Once a user uses Service Desk to send in an email, an issue is automatically created. There is nothing special about that issue at all, except that we know it was a service-desk-generated issue since the author of the issue is support-bot. So once that issue is created, it will always appear in the issues list (e.g. https://gitlab.com/gitlab-org/gitlab-ee/issues), even if Service desk is turned "off". We are currently not doing anything special in the UI or system logic to prevent those service-desk-generated issues from appearing.

Since the main issues list (gitlab-ee/issues) would show Service desk issues, I think we should also show Service desk issues on this page, regardless if the feature is turned on or off. In other words, turning on/off applies to new incoming emails. It doesn't have anything to do with existing service desk issues.

I missed the comment here (and the graphic), https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_38483516. We should have talked about it then.

So if you agree with the ideas above, I think my design in https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_38822352 would still make sense. We don't need a separate graphic. We use the same graphic and UI as https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_36904752 in both scenarios (on / off), with slightly different words / buttons as mentioned in https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_38822352

@victorwu I think that's possibly clutter for projects that will never use SD (like this project!), but maybe I'm wrong.

So if you agree with the ideas above, I think my design in https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_38822352 would still make sense. We don't need a separate graphic. We use the same graphic and UI as https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_36904752 in both scenarios (on / off), with slightly different words / buttons as mentioned in https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_38822352

Sure, that makes sense @victorwu. What I am trying to clarify here is the empty state, regardless of whether it is tied to Service Desk being on or off. There was never a clear decision on that and that scenario is not covered in the statement or design links in your comments above.

I think that's possibly clutter for projects that will never use SD (like this project!), but maybe I'm wrong.

I agree with @smcgivern on this -- although, as one of the purposes of this issue is to increase awareness of Service Desk, we may want to err on the side of keeping it in the UI to help with discoverability. @victorwu maybe you can shed some light on how you think about that tension (clutter vs. discoverability)?

@victorwu @sarrahvesselov Service Desk, service desk, or Service desk? We've been somewhat inconsistent in this issue.

I see that it should always be Service desk @brycepj

Actually, hold on @brycepj, I see that Cycle Analytics is capitalized and not sentence case which I thought was the rule. Let me clarify.

I spoke with @tauriedavis to double check this one @brycepj.

Titles in the nav should be capitalized because it is referencing the feature, not the object... Same as for "Merge Requests" "Cycle Analytics" etc.

On the page itself, we reference the objects, so it is sentence case.

Therefore, it should be Service Desk in the title for the nav. Within the page it should be sentence case.

@hazelyang please double check the designs to be sure we are remaining consistent.

@sarrahvesselov : So whether service desk is on / off is not relevant. So let me use the following definition:

• Non-empty state: There is at least one service desk issue.
• Empty state: There is no service desk issues.

In both cases, I think the doc box is already sufficient. We can include the graphic in https://gitlab.com/gitlab-org/gitlab-ee/issues/3049#note_38483516, instead of the doc box, for the empty state case. But that seems unnecessary, since the copy is essentially the same. The main difference is that the graphic is larger and more prominent. Are you saying that is important and we should have that design?

@smcgivern @brycepj : I think the service desk link should always persist in the sidebar. I think it is worth it to put it there at least for this iteration, given that the goal is to increase usage.

Yet another case I failed to consider. What happens when the issues functionality itself is disabled? How about this:

• Issue tracker on, service desk on: Show service desk nav
• Issue tracker on, service desk off: Show service desk nav
• Issue tracker off, service desk on: Do not show service desk nav
• Issue tracker off, service desk off: Do not show service desk nav

When there are no issues, to me, the docbox alone looks funny. There's just too much whitespace on the page, and it doesn't match the way our other empty states look.

Fwiw, I've already written the code such that an empty state and the docbox can be styled differently, but use the same content. So we're not duplicating anything. Also, @victorwu, in case you're concerned having two different displays will take extra work, it's already done, and wasn't too difficult.

What happens when the issues functionality itself is disabled?

@victorwu It's possible for service desk to be enabled without issues? IMO, if it is, it probably shouldn't be. Although maybe there's something I'm missing?

When there are no issues, to me, the docbox alone looks funny. There's just too much whitespace on the page, and it doesn't match the way our other empty states look.

I feel the same way as @brycepj. The service desk banner should not double as an empty state. They are two separate UX Paradigms. We should use the empty state graphic @hazelyang designed when there are no issues to show.

@sarrahvesselov @brycepj :

I updated the description per your feedback. There are four cases that I've outlined. To be clear:

• Empty vs non-empty states simply means if the search bar filter gives you any results. If there are no results, then it's an "empty state".
• If SD is off, there's no magic SD email address to display. And there's a call to action to go to the settings page. If SD is on, there is a magic SD email to display.

@brycepj : You are right, it doesn't make sense for this feature if issues is off. Let's implement per requirements in description, and track a future issue to address what you mentioned. https://gitlab.com/gitlab-org/gitlab-ee/issues/3292

changed the description

Beautiful, thanks @victorwu!

@victorwu fwiw, there should only be three cases, since you can't have both SD off and non-empty issues. Right?

@brycepj : I think you can because you can turn off SD after some issues already have been created.

closed via merge request !2733 (merged)

mentioned in commit f39f0af7

mentioned in issue #3396 (closed)

mentioned in issue #3509 (closed)

mentioned in issue #3495

mentioned in merge request !2912