Conversation
✅ Deploy Preview for criipto-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
nmoskaleva
force-pushed
the
update-how-it-works-sections
branch
from
60b7b39 to
8a6f719
Compare
nmoskaleva
force-pushed
the
update-how-it-works-sections
branch
from
8a6f719 to
c88564a
Compare
nmoskaleva
changed the title
nmoskaleva
force-pushed
the
update-how-it-works-sections
branch
from
c88564a to
87e0a93
Compare
nmoskaleva
force-pushed
the
update-how-it-works-sections
branch
3 times, most recently
from
cb921dc to
4e6a491
Compare
|
Where does "How it works" fit in the diataxis framework? |
| @@ -2,33 +2,33 @@ | |||
| product: verify | |||
| category: How it works | |||
There was a problem hiding this comment.
Maybe not ideal for "How it works"?
There was a problem hiding this comment.
Hmm, to me, this reads as an explanation and reasoning for making certain implementation choices. This is not a guide or a reference. Where do you think it belongs?
| pathname.startsWith('/verify/reference/authorization-flows/implicit-flow') || | ||
| pathname.startsWith('/verify/reference/authorization-flows/pkce') || | ||
| pathname.startsWith('/verify/reference/authorization-flows/ciba') || | ||
| pathname.startsWith('/verify/reference/authorization-flows/headless') |
There was a problem hiding this comment.
This seems a tad hacky?
There was a problem hiding this comment.
@mickhansen Would you mind if I make a separate PR for that? I agree now that we have 3 subindex pages, they deserve some better logic 😊
There was a problem hiding this comment.
@nmoskaleva But I don't quite understand the purpose of the hack? Why do we need the explicit path matching?
There was a problem hiding this comment.
For the subindex pages to display a better breadcrumb path on mobile, see for instance PKCE or specific errors @mickhansen
This was introduced when we had a single subindex page for Articles, but I added some more subindex pages since then.
Explanation, so conceptual learning (therefore no direct instructions and how-to's) @mickhansen |
|
@mickhansen The category is "How it works", but the titles don't usually correspond with the category. I'll try to find a better title though, to clarify what the section is about. |
@nmoskaleva I realized! My mistake, deleted my comment |
fkj
left a comment
fkj
left a comment
There was a problem hiding this comment.
Generally looks really good to me! I only spotted one small formatting issue.
kasperhj
left a comment
kasperhj
left a comment
There was a problem hiding this comment.
I like the "authorize request parameters" overview. An upgrade could be to make the concepts linked, so clicking e.g. "prompt" would take you to the "prompt" section.
I think the tenants/app/domains reads nice.
I think diagrams are a great way of getting an overview, but to me they are a bit confusing. It's not entirely clear who the main audience is or what we would provide them with:
-
For technical competent people, I think it would be great to include the user agent as an participants and separate auth and token endpoints into two participants grouped under AS (instead of indicating it through activations).
-
For technical incompetent people, I think we could provide a simpler diagram still using the 3 participant model, just calling AS/OP Idura Verify and Client Application something like "your website/app", ditch redirect_uri, id_token, access_token, etc.
I think we're appealing more to the technical competent people with these docs, so I think it could be slightly more technical.
This could easily wait for another day and another PR.
nmoskaleva
force-pushed
the
update-how-it-works-sections
branch
from
4e6a491 to
916131f
Compare
|
"How it works" ends up pretty far down in the navigation on the left hand side. |
I think it would even make sense to put "How it works" at the top of the navigation bar. |
Interesting idea, I can see how it might make sense to move Idura Verify overview to the top level. But as of now, "How it works" has OIDC introduction, which mostly relates to Verify. While top navbar resources relate to all our products. |
@nmoskaleva I think @fkj meant top of the left hand navigation, not the top navigation |
Yeah that's what I meant :) Sorry that was unclear. |
nmoskaleva
force-pushed
the
update-how-it-works-sections
branch
from
916131f to
7b1fae9
Compare
|
@kasperhj Thank you! The request parameters table now points to the individual parameter description. |
This section was previously hidden inside OIDC introduction. This PR improves the information architecture by moving it into a dedicated Reference page, separating the API specifications from "how it works" part.
The "Using OpenID Connect" page previously contained both high-level description and technical implementation details of OIDC authorization flows. This commit extracts the technical details into dedicated reference pages. The original page in the "How it works" section now serves only as a high-level overview.
Update and restructure the page so that it acts as a conceptual guide (rather than a How-to with UI instructions). The flow is slightly reordered to introduce the concept of Applications before Domains to help reader build a mental model without unecessary cognitive load.
…ross-referencing, etc.
nmoskaleva
force-pushed
the
update-how-it-works-sections
branch
from
c8f134d to
b99fb3b
Compare
4 participants
QA: Please take a look at the updated How it works section and the new reference pages (Authorization flows and request parameters).
The "Using OpenID Connect" page previously contained both high-level descriptions and technical implementation details of OIDC authorization flows. This commit extracts the technical details into dedicated reference pages. The original page in the "How it works" section now serves only as a high-level overview.
This section was previously hidden inside OIDC introduction. This PR improves the information architecture by moving it into a dedicated Reference page, separating the API specifications from "how it works" part.
Update and restructure the page so that it acts as a conceptual guide (rather than a How-to with UI instructions). The flow is slightly reordered to introduce the concept of Applications before Domains to help reader build a mental model without unnecessary cognitive load. (@kasperhj based on your advice in Update Verify's "Getting Started" section #308)