Spike - Take a second look at sitemap urls

Before we commit to changing all the urls in the current site, we should take a second look at the sitemap as currently proposed.

Example - There are many ways of getting to view a candidate profile as an admin - through the users table, or when viewing members of a pool, or when viewing the results of a request. These are currently in the sitemap as different urls, but can probably all be the same one.

Here's a big mess of thoughts, to be organized later:

I'm not sure if /indigenous-it-apprentice should redirect to /browse/pools/:id/talent. Even if we're modelling it as a Pool on the backend, the UI may be quite different, so maybe its url should be more unique too. We can reconsider this when we have a better of the actual UI.
if we have /browse/talent and /browse/pools, does just /browse lead anywhere? If not, we could just have /pools and /talent.
In api design, resources are usually pluralized. /users, /pools, etc. Is the concept of "portal" (eg /admin, /pool-owner, etc) different enough that they should NOT be pluralized?
Current site map uses
- /browse/pools/:id to view a Direct Intake poster
- /browse/pools/:id/apply to apply to that pool
- /browse/pools/:id/talent to search that pool
- /browse/talent to search all talent.
- I'd like to suggest we chop the /browse off the front, and replace "talent" with "browse":
  - /pools to view all direct intake posters
  - /pools/:id to view details of a pool
  - /pools/:id/apply to apply to the pool
  - /pools/:id/browse or /pools/:id/search to search that pool
  - /browse or /search to search all talent
- But... are all searchable pools Direct Intakeable? If the list of pools I can search for is different from the list of pools I can apply to, maybe they need two different urls:
  - /pools for applyable pools
  - /search/pools for searchable pools?
We tend to think about different "portals", since that's how Talent Cloud was organized: Applicants, Manager, Admins. But maybe its not the right model now.
- Talent Search is not on a seperate portal, so the /talent-seeker functionality shouldn't be. We could just hide certain nav menu items and pages unless a user has the talent-seeker role.
- Similarly for Pool Managers and Admins. They do very similar things, they can probably use the same /admin/... urls, with different functionality exposed.
/user/profile :
- we could force users to /user/:id/profile instead. That would make it possible for Admins to access these pages.
- we could have /user/me redirect to /user/:id
- we could leave users at /user/me, and it wouldn't stop us from creating /user/:id routes for admins. Although, it would make it harder for users to share the link - admins would have to look up their id first.
- what is at /user ? Or /user/:id? A dashboard? A public profile? If something public, that's another reason for going the /user/:id route.
Instead of /user, should we use a more specific term like /applicants or /candidates
Instead of /pool-owner and /manager, maybe /pool-manager and /talent-seeker?
Should different roles provide their own endpoints for resources? eg, if Talent Seekers want to view a candidate profile, should they go to /users/:id or should it be /talent-seekers/users/:id?
- Well... if the role requires a specific way of interacting, or a specific subset of information, they should probably have their own view.
- Pool managers need several ways of looking at candidates: one view to interact with a user as a Pool Candidate (or applicant to a pool), and one view to interact with users as a result of Talent Requests.
- Pool need another way to interact with Users, in order to promote their roles, and maybe to add them to pools.
- Should Pool Managers use a different set of urls from Admins, even though a lot of the UI overlaps? If anything, Pool Managers just have access to a subset of the functionality. We could use the same urls, but hide certain menu links and certain buttons for non-admins.

I'm not sure if /indigenous-it-apprentice should redirect to /browse/pools/:id/talent. Even if we're modelling it as a Pool on the backend, the UI may be quite different, so maybe its url should be more unique too. We can reconsider this when we have a better of the actual UI.

+1 to to redirect for starters. wondering if adding ?layout=iap could support variations to start. That pattern could work on other pages, and avoid a proliferation of IAP-specific components from the get-go.

if we have /browse/talent and /browse/pools, does just /browse lead anywhere? If not, we could just have /pools and /talent.

In api design, resources are usually pluralized. /users, /pools, etc. Is the concept of "portal" (eg /admin, /pool-owner, etc) different enough that they should NOT be pluralized?

It feels less important to pluralize, as it's different from other entities in the path. it's a filter over endpoints, more conceptually like a query param ?role=admin imho

Current site map uses

/browse/pools/:id to view a Direct Intake poster

/browse/pools/:id/apply to apply to that pool

/browse/pools/:id/talent to search that pool

/browse/talent to search all talent.

I'd like to suggest we chop the /browse off the front, and replace "talent" with "browse":

/pools to view all direct intake posters

/pools/:id to view details of a pool

/pools/:id/apply to apply to the pool

/pools/:id/browse or /pools/:id/search to search that pool

/browse or /search to search all talent

But... are all searchable pools Direct Intakeable? If the list of pools I can search for is different from the list of pools I can apply to, maybe they need two different urls:

/pools for applyable pools

/search/pools for searchable pools?

We tend to think about different "portals", since that's how Talent Cloud was organized: Applicants, Manager, Admins. But maybe its not the right model now.

Strongly in favour of eventually migrating away from portal-based considerations in urls.

Questions that make me squeamish:

What happens if we encounter a need to divide a single role into two? What happens if we discover the need to move a task/responsibility between roles? What happens if we're asked to rename a role?
What happens to our documentation or any links outside the app (e.g. email) when the above happens?
Will we be inclined to resist the above requests?

In my experience, urls/paths are a longterm commitment to the location of an entity on the internet, e.g., a user profile, a pool, a candidate, a request). By adding roles into the url, we break this informal contract and lose this helpful assumption as we evolve the platform.

My impression is that the more we put in the path parts, the more constrained.

imho, the less url parts/depth needed to point to the authoritative and longterm "home" for an entity (entity = profile, user, pool, skill, etc), the better.

For e.g., it was many years (and massive scale) before GitHub chose to add even a second layer of entities (and seemingly related to the team entity not making sense outside the org entity): https://github.com/orgs/CivicTechTO/teams/project-leads/members https://github.com/orgs/{:orgId}/teams/{:teamId}/members

Talent Search is not on a seperate portal, so the /talent-seeker functionality shouldn't be. We could just hide certain nav menu items and pages unless a user has the talent-seeker role.

+1 to role-based rendering

Similarly for Pool Managers and Admins. They do very similar things, they can probably use the same /admin/... urls, with different functionality exposed.

+1 as less different "role paths", if we must keep them.

/user/profile :

we could force users to /user/:id/profile instead. That would make it possible for Admins to access these pages. 👍

we could have /user/me redirect to /user/:id 👍

we could leave users at /user/me, and it wouldn't stop us from creating /user/:id routes for admins. Although, it would make it harder for users to share the link - admins would have to look up their id first.

👍 to using /user/me as 301 redirect, not dup page url

what is at /user ? Or /user/:id? A dashboard? A public profile? If something public, that's another reason for going the /user/:id route.

This is my happy-place with this: /<plural-noun>/{:id | me | <placeholder>}/<optional-modifier-verb> and maybe rarely a second layer of noun-id pairs beyond the first, when the second-layer makes very little sense as an independent entity
me is a special-case that resolves to user's own :id
placeholder = during creation, as a placeholder for to-be-created :id (e.g., "new" or "create")

Instead of /user, should we use a more specific term like /applicants or /candidates

👎 seems better to keep it general, so that this path can be linked to from anywhere without seeming like a misalignment. For example, maybe we'll realize down the road that admins could benefit from user pages for some reason.

Instead of /pool-owner and /manager, maybe /pool-manager and /talent-seeker?

Should different roles provide their own endpoints for resources? eg, if Talent Seekers want to view a candidate profile, should they go to /users/:id or should it be /talent-seekers/users/:id?

👍 for /users/:id (avoiding role-dependent paths if at all possible)

Well... if the role requires a specific way of interacting, or a specific subset of information, they should probably have their own view.

Yes, but still feels ideal, if possible, that the affordances for that different way of interacting were simply new UI elements on those existing pages.

E.g., Instead of pointing to <blah>/pools/{:poolId}/applicants/{:id}/profile, could <blah>/pools/{:poolId}/applicants just point to something like <blah>/users/{:id}?pool_id={:poolId} and render with any additional elements based on query param and/or role?

Same with talent requests.

Pool managers need several ways of looking at candidates: one view to interact with a user as a Pool Candidate (or applicant to a pool), and one view to interact with users as a result of Talent Requests.

Pool need another way to interact with Users, in order to promote their roles, and maybe to add them to pools.

Should Pool Managers use a different set of urls from Admins, even though a lot of the UI overlaps? If anything, Pool Managers just have access to a subset of the functionality. We could use the same urls, but hide certain menu links and certain buttons for non-admins. 👍

While working on the register page, I noticed something that is not necessarily an issue, just kinda odd. Each of the new auth pages are root paths which means we need to add each to the .htaccess file to point to talentsearch project.

I know we discussed merging all of the projects which would resolve this, however, in the meantime should we just keep tacking on to .htaccess or do we want to add them all under a base /auth path?

~~This would fix our issue with the contradicting /login paths and make it so one .htaccess rule would be sufficient.~~

/auth/login
/auth/logout
/auth/logged-out
/auth/create-account

To summarize some of the discussion between @patcon and I...

Some assumptions:

shorter urls (ie fewer path segments) are better. Easier to read, less complex to maintain.
Ideally, a single resource is always presented at a single url. This simplifies navigation and is better for SEO. Minor variations to the page can be introduced depending on the logged-in user and their role.
Entirely different modes of interaction with the same resource can merit different urls

Some proposals:

Browse pages

The /browse segment in the current sitemap seems extraneous. Also, the /talent segment might feel a bit redundant whent our domain is talent.canada.ca. So, I suggest removing the browse segment and changing talent to search or browse. So, instead of:

/browse/pools to view pools available to apply to
/browse/pools/:id to view a Direct Intake poster
/browse/pools/:id/apply to apply to that pool
/browse/pools/:id/talent to search that pool
/browse/talent to search all talent. we move to
/pools to view pools available to apply to
/pools/:id to view a Direct Intake poster
/pools/:id/apply to apply to that pool
/pools/:id/search to search that pool
/search to search all talent.

Profile urls

This isn't a strict suggestion so much as a discussion topic, because I see pros and cons to both options.

Instead of sending a user to /user/profile to view their profile, we could send them to /users/:id/profile, where :id is their own id.

Pros:

easy to copy and paste the url to share their profile with a manager, or with an admin as part of tech support
we don't have to maintain separate urls for when managers need a way to view applicant profiles

Cons:

Unless we implement some sort of username/slug system, the id in the url will be a long, ugly, impossible to remember uuid
We'd need to maintain a /users/me/profile url, which looks up the current user's id and redirects them to the proper url.

"Pool-owner" portal

It sounds like Lauren wants to keep a /managers homepage/portal as its own thing. It may make sense to move the talent search pages under this path.

However, pool-owner's probably don't need their own "portal". They can use the same /admin urls we've been creating. If some elements of pages are only for admins, we can hide/show them based on the logged-in user's role.

The /browse segment in the current sitemap seems extraneous. Also, the /talent segment might feel a bit redundant whent our domain is talent.canada.ca. So, I suggest removing the browse segment and changing talent to search or browse.

Agree 💯

Instead of sending a user to /user/profile to view their profile, we could send them to /users/:id/profile, where :id is their own id.

Pretty sure this is how almost all sites handle this. They show the same page and add controls based on the authenticated user.

We'd need to maintain a /users/me/profile url, which looks up the current user's id and redirects them to the proper url.

I'm not sure I understand why we would need to maintain this URL, would we not just pass the uid into the path function? i.e

const paths = useApplicantProfileRoutes();

return (
 <Link href={paths.profile('uid')}>My Profile</Link>
);

I'm not sure I understand why we would need to maintain this URL [/users/me]

Uhhh... hm. You're right, maybe we don't need that. I was thinking there might be a case where we'd want to show a link to a non-logged-in user, which would force a login and deep-link back to their profile. But maybe it doesn't make sense to show that to a non-logged-in user at all.

Thanks for summarizing Tristan.

Feeling alignment with Eric's comment.

Though the /users/me/profile is more for practical stuff that's off-app (and which we otherwise lose by abandoning the approach of /users/profile). E.g., a doc or email template that can just link to that path, and app will redirect appropriately after sign-in. But it's easy enough to add when it's needed :)

I've changed our go.talent.c4nada.ca/sitemap shortlink to point to a google sheet instead of a figjam board, to make it easier for all team members to edit if need be.

I've made the updates we discussed to the document! There's still lots of room for it to continue to evolve.

GCTC-NTGC / gc-digital-talent