Skip to content

Commit 1d76674

Browse files
domoscargindomoscargin
authored
Merge pull request #28 from alphagov/support
Add documentation on supporting our users
2 parents 49e2e6c + ad2deae commit 1d76674

File tree

8 files changed

+858
-6
lines changed

8 files changed

+858
-6
lines changed

‎source/support/assets/images/github-notifications-view.png

44.1 KB
Loading

‎source/support/communicating-with-users/common-responses.html.md

Lines changed: 535 additions & 0 deletions
Large diffs are not rendered by default.

‎source/support/communicating-with-users/index.html.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Communicating with users
3+
weight: 4
4+
---
5+
6+
# Communicating with users
7+
8+
Follow the [Design System communications charter]
9+
10+
## Responding to users
11+
12+
If someone asks a question or reports a problem you should respond to acknowledge their questions. Being able to take part in team meetings takes priority over support.
13+
14+
When you respond you should consider:
15+
16+
- discussing the query with another person on the team if complex
17+
- if there is something in the Design System or Frontend that can help this person?
18+
- if we don’t have something but it lives in the community backlog, share the specific issue and say that people across government have shared work in progress that might help them
19+
- whether you or someone in the team can help this person?
20+
- if not, identify who is best placed from GDS to refer to
21+
22+
**Just because you're on support doesn't necessarily mean you're the right person to respond to a particular query. Your role is to identify the right person and liaise.**
23+
24+
In addition to this, if you are not on support but feel best placed to answer a particular query, please discuss it with the designated support volunteers before replying.
25+
26+
Then:
27+
28+
* if the Design System does not contain guidance, but we want to give an opinion, we need to make it clear that it's a personal opinion and not a representation of GDS.
29+
* if it’s something that someone else in the team can help with get them involved (only in the case if the issue is preventing the user from being able to use the products)
30+
* If it’s a bug, ask if it's possible for them to raise an issue in the corresponding repository (unless that is how the support request comes in). Say “if you are not able, I can do this for you” Make sure you ask them if we can mention their name or prefer it to be anonymous.
31+
* If you think the user might be able to fix the bug themselves (for example, if they provide a ‘suggested fix’), ask them if they would be willing to do so, encouraging them to raise a pull request.
32+
* Otherwise, if the bug is something that is easy to fix, and you are able to fix it, you can do so, following our usual development practises.
33+
* if they are requesting something new or a regression from the old products, thank them for raising, explain that it doesn’t exist and encourage them to raise a PR
34+
* If you need more information from them to answer their query, ask for it. If the query is via Zendesk and you don’t hear back within a week, you can close the issue - but send a message explaining why. If you need to open the issue at a later date, you’ll need to [create a Follow up ticket]
35+
36+
If a question is a broader one that cannot be solved at the moment but should be captured (eg. a discussion about whether it’s useful to add “or” between radio button options), try to nudge the conversation towards the [backlog] by saying that the feedback is really valuable and we don’t want it to get lost from Slack.
37+
38+
Use this [guide to identify if a query is a feature or a bug].
39+
40+
[backlog]: https://github.com/alphagov/govuk-design-system-backlog
41+
[create a Follow up ticket]: https://support.zendesk.com/hc/en-us/articles/203690986-Creating-a-follow-up-for-a-closed-ticket
42+
[Design System communications charter]: https://docs.google.com/document/d/119d3menyPzJ4R4GJEsgAWRaair9ueuamCqxUKDLkuNI/edit
43+
[guide to identify if a query is a feature or a bug]: https://docs.google.com/document/d/1DthS8EVbUiGJvss4mw-irEjvkkX7mqT9n4fBbRHjFz8/edit

‎source/support/index.html.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
title: Support
3+
weight: 12
4+
---
5+
6+
# Support
7+
8+
See the “[Support Model Blueprint](https://docs.google.com/drawings/d/1ox2FK9q6GRyY_zvhSuFIOT9-a6Wd-R4-kP8OlrzVCvk/edit)”
9+
10+
- [Products we support](./products-we-support/)
11+
- [Support channels](./support-channels/)
12+
- [Daily support responsibilities](./support-responsibilites/)
13+
- [Communicating with users](./communicating-with-users/)
14+

‎source/support/index.html.md.erb

Lines changed: 0 additions & 6 deletions
This file was deleted.

‎source/support/products-we-support/index.html.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Products we support
3+
weight: 1
4+
---
5+
6+
# Products we support
7+
8+
## Current products
9+
10+
- [GOV.UK Design System website]
11+
- [GOV.UK Frontend]
12+
- [Community backlog]
13+
14+
## Legacy products
15+
16+
We support a number of ‘legacy’ products which GOV.UK Frontend and GOV.UK Design System replaced, which we still need to provide some support for:
17+
18+
- [GOV.UK Elements]
19+
- [GOV.UK Frontend Toolkit]
20+
- [GOV.UK Template]
21+
22+
The websites and repositories for these projects should state something along the lines of:
23+
24+
> The Government Digital Service (GDS) is retiring [Product Name] following the launch of the GOV.UK Design System. [Product Name] will remain available to you if you are currently using it but will no longer be maintained. GDS will only roll out major bug fixes and security patches.
25+
26+
What we mean by ‘major bug fixes and security patches’ is loosely defined, which allows us some flexibility, but broadly speaking we expect to fix issues which affect the accessibility or usability of a service using our legacy products. We would only fix ‘cosmetic’ bugs if they were severe enough that they would otherwise reduce the trust the user has in the service.
27+
28+
Security issues should be addressed, but only if they impact the services that use them.
29+
30+
## No longer supported
31+
32+
### [GOV.UK Prototype Kit]
33+
34+
As of May 2023, the Prototype team will handle any queries regarding the Kit. The Design System team can redirect Kit queries to the cross-gov slack channel #prototype-kit, or hand over queries either via the Prototype team Slack channel or via [email][GOV.UK Prototype Kit Email]
35+
36+
### [Accessible Autocomplete]
37+
38+
We’re not currently supporting the autocomplete repo
39+
40+
[Accessible Autocomplete]: https://github.com/alphagov/accessible-autocomplete
41+
[Community backlog]: https://design-system.service.gov.uk/community/backlog/
42+
[GOV.UK Design System website]: https://design-system.service.gov.uk/
43+
[GOV.UK Elements]: http://govuk-elements.herokuapp.com/
44+
[GOV.UK Frontend]: https://github.com/alphagov/govuk-frontend
45+
[GOV.UK Frontend Toolkit]: https://github.com/alphagov/govuk_frontend_toolkit
46+
[GOV.UK Prototype Kit]: https://govuk-prototype-kit.herokuapp.com/docs
47+
[GOV.UK Prototype Kit Email]: govuk-prototype-kit-support@digital.cabinet-office.gov.uk
48+
[GOV.UK Template]: http://alphagov.github.io/govuk_template/
49+

‎source/support/support-channels/index.html.md

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: Support channels
3+
weight: 2
4+
---
5+
6+
# Support channels
7+
8+
Turn on notifications for the following channels and check them regularly through the day:
9+
10+
## Slack
11+
12+
[#govuk-design-system][#govuk-design-system-xgov] channel on Cross Government Slack
13+
[#govuk-design-system][#govuk-design-system] channel on GDS Slack
14+
15+
You can choose to monitor other channels (like #design or #frontend), but we don’t officially support them.
16+
17+
### Inviting people to Slack
18+
19+
#### Joining Slack
20+
21+
Those with a government email address can just join the [cross government Slack].
22+
23+
There isn’t an up-to-date list of the email domains that have been approved as a government email address for this Slack instance ([this is the last available list][xgov-domain-list] but it’s not being kept up-to-date anymore).
24+
25+
#### Being invited to Slack
26+
27+
Occasionally we have people ask us for access to the cross-government Slack when their email hasn’t been approved as a government email address (see above).
28+
29+
To invite someone, just say `/invite <email>`in Slackbot (your private bot channel). The invite request then goes to the Slack workspace admins who decide whether to approve it.
30+
31+
The good news is that once someone’s invite has been approved by the Slack workspace admins, that person can then invite others on the same email domain themselves by using `/invite`.
32+
33+
#### Single channel guests
34+
We have previously added people outside the organisation to the GDS Support Slack channel in order to provide support if they’re undertaking a piece of work in government but can’t get on cross government Slack. Ideally the period they need to be invited for won’t be very long.
35+
36+
To add a single channel guest:
37+
38+
1. Follow the [guidance to invite the guest] (under ‘Guest accounts’). Cc in another member of our team for visibility on the IT ticket.
39+
2. Post a message on our team Slack telling them about the single channel guest.
40+
3. When the user is added to the support Slack channel, post the following messages there:
41+
- “Hello x and welcome!”
42+
- “Hello everyone. X works for an external organisation on behalf of GDS and has joined this channel temporarily to get support on using the Design System.”
43+
44+
Create a team calendar event for checking the day after the account closure date set in the IT ticket whether the person has been removed from the Slack support channel. If not, leave a message on the IT ticket to remove the user.
45+
46+
## Github
47+
48+
- govuk-frontend [issues][govuk-frontend-issues] and [pull requests][govuk-frontend-prs]
49+
- govuk-design-system [issues][govuk-design-system-issues] and [pull requests][govuk-design-system-prs]
50+
- govuk-design-system-backlog [issues][govuk-design-system-backlog-issues]
51+
52+
Whilst on daily support, any new pull requests or issues raised that day should be reviewed.
53+
54+
All new pull requests should be added to the sprint board. At the next stand up the team will identify reviewers.
55+
56+
For new issues you should:
57+
58+
1. Flag in the team Slack channel if you think the issue meets the below high-priority criteria and add `high-priority` label:
59+
- A bug which renders something unusable
60+
- A WCAG failure
61+
- An issue which has been raised by users on more than 5 occasions (tracked by adding comments to the GitHub issue each time it appears on support)
62+
2. The `submitted-by-user` label should be added to any issues opened on behalf of a user. This will help us further down the line when we do an analysis.
63+
3. Add estimate labels
64+
- `🕔 hours`: a well understood issue which we expect to take less than a day to resolve. Could be something that community could be involved in (eg. first timer issues).
65+
- `🕔 days`: a few unknowns, but we roughly know what’s involved. We’d expect it to take less than a week to resolve. May be a good thing to pair on.
66+
- `🕔 weeks`: This is complicated and will require a lot of effort from the team, taking more than a week to resolve. May need breaking down into smaller pieces of work.
67+
4. Add other appropriate labels such as related components and patterns or themes
68+
69+
If you need help from the team to triage an issue, use the team Slack channel to ask.
70+
71+
### How to see new issues, PRs and comments on our repos
72+
73+
There is a view you can set up in GitHub which will notify you when new issues / PRs / comments are added to a repository. This could be useful when you are on support.
74+
75+
Go to your icon in top-right corner > Settings > Notifications
76+
77+
Skip to ‘Watching’. Untick ‘Email’ and tick ‘Web and Mobile’.
78+
79+
Now select the repositories you want to “watch”. This should be:
80+
81+
- [alphagov/govuk-design-system]
82+
- [alphagov/govuk-frontend]
83+
- [alphagov/govuk-design-system-backlog]
84+
85+
You can watch each of these repositories by selecting the ‘Watch’ drop-down in the top right and selecting ‘All activity’.
86+
87+
To get the notifications view, click on [this link][github-notifications-view]
88+
89+
It should look like this:
90+
91+
![Github notifications view](../assets/images/github-notifications-view.png)
92+
93+
### Recording new queries relating to an existing issue
94+
95+
If you receive a query regarding an issue which already exists on one of our repositories, add a comment to that issue noting that this has appeared on support that day. When we reach 5 instances of this, add the “high priority” label and flag in the team Slack channel.
96+
97+
### Responding to Community Backlog issues and comments
98+
99+
- Make sure you are responding to comments that need our team’s answer.
100+
- Keep an eye on the [latest comments]
101+
- To have an overview, check the [project board][govuk-design-system-backlog-issues]
102+
103+
### Adding newly raised issues to the board
104+
105+
We ask contributors to [get in touch with us when they raise a new issue][raise-issue] in the backlog.
106+
107+
This is so we can help them:
108+
- briefly review the issue to make sure it’s appropriate
109+
- add it to the [GitHub projects ‘list view’][govuk-design-system-backlog-issues-list] of the backlog
110+
111+
## Email
112+
113+
Emails sent to our support email address are automatically turned into [Zendesk] tickets. If you are part of the support rota you will be given access to Zendesk. See this guide on [how to use Zendesk][Zendesk-help] for more details.
114+
115+
### Mailing list
116+
117+
We have a mailing list for users to subscribe to emails about future updates and events.
118+
119+
In most circumstances users can sign up to the mailing list using the link on the Design System homepage, which takes them to a Mailchimp landing page with a signup form.
120+
121+
However if for whatever reason the Mailchimp form isn’t an option then users can also email the support inbox to ask for us to sign them up.
122+
123+
If a user sends an email asking to join the mailing list, but without having selected any of the options for things they are interested in, we should reply with something like
124+
125+
> Thank you for your interest in emails from the GOV.UK Design System team.
126+
>
127+
> It looks like you have not selected anything under the types of emails you’d like to receive. Could you reply with at least one option selected?
128+
129+
Once the user has clarified which topics they want to hear about you can add them to mailchimp manually by:
130+
131+
1. [Logging into mailchimp][mailchimp]. Credentials can be found in the Design System team’s Bitwarden account.
132+
2. Navigate to Audience (left hand sidebar) > All contacts > Add contacts > Add a subscriber
133+
3. Fill out the Add subscriber form
134+
- Enter the user’s email address
135+
- Check the topics the user expressed interest in
136+
- Check the boxes at the bottom relating to the person giving you permission to email them and to update their profile if they already have one
137+
- Click subscribe
138+
4. Go back to the ticket and let the user know that they’ve been added:
139+
140+
> We've added you manually to our mailing list with the requested settings. Please feel free to contact us in future if you require further assistance.
141+
142+
## Analysing our support requests
143+
144+
On a monthly basis, we will pull all the tickets from GitHub repos, slack and zendesk into the [support log spreadsheet]. We will be able to search and filter by time, channel and tag. We will use this data to identify areas the users need the most support and define epics/stories from that or plan further research.
145+
146+
We also hold bi-weekly sessions to give tags to Slack messages.
147+
148+
[#govuk-design-system]: https://gds.slack.com/messages/CAF8JA25U
149+
[#govuk-design-system-xgov]: https://ukgovernmentdigital.slack.com/messages/govuk-design-system
150+
[alphagov/govuk-design-system]: https://github.com/alphagov/govuk-design-system
151+
[alphagov/govuk-frontend]: https://github.com/alphagov/govuk-frontend
152+
[alphagov/govuk-design-system-backlog]: https://github.com/alphagov/govuk-design-system-backlog
153+
[cross government Slack]: https://ukgovernmentdigital.slack.com/
154+
[github-notifications-view]: https://github.com/notifications?query=repo%3Aalphagov%2Fgovuk-design-system-backlog+repo%3Aalphagov%2Fgovuk-design-system+repo%3Aalphagov%2Fgovuk-frontend+
155+
[govuk-design-system-issues]: https://github.com/alphagov/govuk-design-system/issues
156+
[govuk-design-system-prs]: https://github.com/alphagov/govuk-design-system/pulls
157+
[govuk-design-system-backlog-issues]: https://github.com/orgs/alphagov/projects/43
158+
[govuk-design-system-backlog-issues-list]: https://github.com/orgs/alphagov/projects/43/views/2
159+
[govuk-frontend-issues]: https://github.com/alphagov/govuk-frontend/issues
160+
[govuk-frontend-prs]: https://github.com/alphagov/govuk-frontend/pulls
161+
[guidance to invite the guest]: https://sites.google.com/a/digital.cabinet-office.gov.uk/gds/information-management/using-online-tools-at-gds/use-gds-slack
162+
[latest comments]: https://github.com/alphagov/govuk-design-system-backlog/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc
163+
[mailchimp]: https://login.mailchimp.com/
164+
[raise-issue]: https://design-system.service.gov.uk/community/propose-a-component-or-pattern/#2-raise-an-issue
165+
[support log spreadsheet]: https://docs.google.com/document/d/1G-TN0uXeKchwhHZnmPveX5YteXi3uSl0Rf5vtg-J5l4/edit?usp=sharing
166+
[support model blueprint]: https://docs.google.com/drawings/d/1ox2FK9q6GRyY_zvhSuFIOT9-a6Wd-R4-kP8OlrzVCvk/edit
167+
[xgov-domain-list]: https://github.com/bruntonspall/xgovslackbot/blob/ae6664437dadb2aef4c21ab97c2818f2ca5f9604/app/domains.js#L9
168+
[Zendesk]: https://govuk.zendesk.com/agent/dashboard
169+
[Zendesk-help]: https://docs.google.com/presentation/d/1VrDAuCm5qm6ULNGRco_deB7EIFf95bHFDlqG-yvLQi4/edit#slide=id.p17
170+

‎source/support/support-responsibilites/index.html.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: Daily support responsibilities
3+
weight: 3
4+
---
5+
6+
# Daily support responsibilities
7+
8+
Our support hours are 10am – 4pm, Monday to Friday.
9+
10+
The support rota is in the ‘[Design System team events]’ calendar. If you know you‘re going to be away or busy on your support day, try to find somebody to swap with on the team Slack channel. If you have an unplanned absence, let the team know on Slack and someone will cover.
11+
12+
At the start of your support day, you should update the Slack channels with something like this message:
13+
14+
> “Hello, I’m on support today from 10am to 4pm if you need any help. You can also direct message me or email govuk-design-system-support@digital.cabinet-office.gov.uk.”
15+
16+
You should also change your display name in Slack.
17+
18+
For example “Kelly Lee - GOV.UK Design System team”.
19+
20+
This is so it is clear to our users which responses are from the team.
21+
22+
Remember to check Zendesk for any open tickets, especially at the start of the day. There may be tickets that came in at the end of the previous day that need responding to.
23+
24+
If a submission to the [Community Resources] list is made whilst you are on support, it is your responsibility to review the submission against the contribution criteria. You may need to ask the contributor for further information or advise changes to the resource in order to meet the criteria, meaning the review could take longer than your support day. In this occurrence, you will continue to own the review of the submission. Ensure that you add any associated GitHub issues or pull requests to the sprint board.
25+
26+
Whilst on support, it is preferable to pause sprint work and prioritise support tasks.
27+
28+
## Daily check in
29+
30+
At the end of each day you should complete the [daily check in form]. In the absence of logging support requests this will help us measure the impact of providing support.
31+
32+
[#govuk-design-system]: https://gds.slack.com/messages/CAF8JA25U
33+
[#govuk-design-system-xgov]: https://ukgovernmentdigital.slack.com/messages/govuk-design-system
34+
[Community Resources]: https://design-system.service.gov.uk/community/resources-and-tools/
35+
[cross government Slack]: https://ukgovernmentdigital.slack.com/
36+
[daily check in form]: https://docs.google.com/forms/d/e/1FAIpQLSdp1Fvypj24N1XoheRPdXbMcB784NZXaqYQkK9zGxSqhohmgg/viewform
37+
[Design System team events]: https://calendar.google.com/calendar/embed?src=digital.cabinet-office.gov.uk_4bkq5dftg4doh71gg8tpelgi0k%40group.calendar.google.com&ctz=Europe%2FLondon
38+
[govuk-design-system-issues]: https://github.com/alphagov/govuk-design-system/issues
39+
[govuk-design-system-prs]: https://github.com/alphagov/govuk-design-system/pulls
40+
[govuk-design-system-backlog-issues]: https://github.com/orgs/alphagov/projects/43
41+
[govuk-frontend-issues]: https://github.com/alphagov/govuk-frontend/issues
42+
[govuk-frontend-prs]: https://github.com/alphagov/govuk-frontend/pulls
43+
[guidance to invite the guest]: https://sites.google.com/a/digital.cabinet-office.gov.uk/gds/information-management/using-online-tools-at-gds/use-gds-slack
44+
[xgov-domain-list]: https://github.com/bruntonspall/xgovslackbot/blob/ae6664437dadb2aef4c21ab97c2818f2ca5f9604/app/domains.js#L9
45+
[Zendesk]: https://govuk.zendesk.com/agent/dashboard
46+
[Zendesk-help]: https://docs.google.com/presentation/d/1VrDAuCm5qm6ULNGRco_deB7EIFf95bHFDlqG-yvLQi4/edit#slide=id.p17
47+

0 commit comments

Comments
 (0)