search

bcgov / api-services-portal

API Services Portal provides a multi-tenant frontend integrating API Gateway and Authorization services from Kong CE and Keycloak.
https://api.gov.bc.ca
Apache License 2.0
22 stars 7 forks source link

Provide navigation links to Get started from the Services Portal #1169

Open timng-bcgov opened 2 months ago

timng-bcgov commented 2 months ago

Priority

Medium

User Story

As a new or existing API provider,
I want to access the information provided on the Get started page
so that I can create and configure Gateway services on the Services Portal.

Test Case

ENV

TESTCASE

Login to the API Services Portal.

EXPECTED

There is/are link(s) to the Get started page from the Gateways manager.

ACTUAL

There are no existing links to the Get started page if you are an existing user of the Services Portal (user with 1 or more Gateways).

Notes

We heard from users during ns-to-gw user acceptance testing that they found the information on the Get started page useful as a reference. The majority of users would like to access this page once they navigate away from it in the Services Portal. We'll need to discuss more about the navigational patterns that we can design to address this issue. One possible solution is to revise the cards on the My Gateways manager, specifically the "Need to create a new Gateway?" item:

image

rustyjux commented 2 months ago

If we are giving users a way back to Get Started, we might want to revise the 'You have Gateways' banner (since it was only made with the new/first time user in mind).

This could include one of:

I'm not sure what would be the best way to determine if we had a returning user vs first time user, if we wanted to make elements conditional based on that.

timng-bcgov commented 2 months ago

The latter option was a suggestion we heard in user testing that's captured in #1166 . I noted the link to this issue in the notes there as well. Which elements (other than the 'You have Gateways' banner) do you think we should make conditional?

rustyjux commented 2 months ago

Right now I'd say some language like 'your first Gateway' (as in 'Steps to create and configure your first Gateway') might want to change but...

Before naming specific changes, how about we spell out the purpose for the Get Started page, both for the first time around and if users revisit? In my mind, this page might be less confusing on a return visit the less that changes. Also, there are some style choice we use here (specifically 'our') which I find feel inappropriate and out of sync with the rest of our content (except for CMS Lite https://www2.gov.bc.ca/gov/content/data/finding-and-sharing/api-management).

Another revision for Get Started (which could be a separate issue) would be to change the page header/title from 'My Gateways' - this doesn't reflect the page content at all, except that you are redirected there from the Gateways tab (which is now 'My Gateways' once you open the page, but we need to revisit the whole 'My' thing).

timng-bcgov commented 2 months ago

Just so that I understand correctly, we are proposing to change the copy on the page with regards to whether the user is a first-time user (no Gateways) or an existing user (1 or more Gateways)?

I agree that we should rename the 'My Gateways' heading on the page. Can we add it to #1143?

rustyjux commented 2 months ago

Just so that I understand correctly, we are proposing to change the copy on the page with regards to whether the user is a first-time user (no Gateways) or an existing user (1 or more Gateways)?

The rough original idea for this page was: give new API provider users a brief welcome to the Portal and a concise set of instructions to follow to gain experience with creating a Gateway (inc. Gateway Service, Product, and Dataset).

We can change components, copy, whatever! if that seems necessary or helpful to suit the context in which users are viewing the page a second time.

Right now some page elements change based on the user state - we added the 'You have Gateways' banner (and removed the 'No gateways' block) so that if users happen to stay on this page after creating a Gateway (as instructions direct them to do), they have some indicators that things have changed from when they first loaded the page.

I agree that we should rename the 'My Gateways' heading on the page. Can we add it to #1143?

Good call - I added Get Started to #1143

timng-bcgov commented 2 months ago

So with regards to what we discussed in sprint planning, how does this look for a proposed solution that can be accomplished this sprint?

image

I think we should defer (conditionally) changing the purpose of the Get started page (walking users through creating their first Gateway) until some more client engagement/ user research is done (cc'ing @ssulehri-gov-bc-ca here).

All of these items are open to discussion, just writing this down so that the next steps can be fleshed out.

rustyjux commented 2 months ago

I'm good with most of those changes. If users go Get Started --> My Gateways, users can use back in the browser in addition to any new link to get back to Get Started from My Gateways.

Minor nit: all page titles (now) are capitalized so it would be 'Get Started' over 'Get started'

The one change I am less sure of is the final point, adding the Get Started link in the 'Need to create a new g(G!)ateway?' card. I think it'd be nice if users didn't need to choose which link to follow. The 'Create a Gateway' how-to is very limited in scope, which is good for the simple straightforward answer to the need of 'Need to create a new Gateway'. It also sends users into DevHub, which is sort of a plus if they haven't made it there yet, or a minus for more context switching...

timng-bcgov commented 2 months ago

I see your point about having the choice of two links and how it might be suboptimal. I placed the link there for visibility and because it addresses the need to create a new Gateway. We could very well present a separate card on the Gateways list (I made some small changes to the copy while mocking up the design):

image

Another solution I'm considering in parallel is to include a link to Get Started from the Help dropdown.

rustyjux commented 1 month ago

I don't love the 4 cards. I do like adding Get Started to help. Not sure if that is adequate as a means for users to get (back) to that page.