Hey HN, author here.

I got some positive feedback on my previous article; Learn OAuth 2.0 by building an OAuth client (https://annotate.dev/p/hello-world/learn-oauth-2-0-by-buildi...) and created a follow up on the OIDC standard.

Let me know what you think and if you have any feedback!

Agreed, I think it's something you should know how to do and then choose not to do it (use an existing library instead). Having a good understanding really helps with debugging issues that come up.

This was my experience as well. I've previously blindly followed instructions from OAuth libraries, but it frustrated me that I didn't fully understand what was going on.

Hey HN, author here.

When I was first learning OAuth, I found that all the guides were text-heavy and lacked code. I personally learn better from code, so I created a code-first guide. Let me know if you have any feedback!

It's a decent skeleton for a server side client. You might consider showing how a token refresh might work.

There is often a need for public client side implementations as well. Are you planning on making one there? It's mostly the same idea but you do the redirects yourself with CSRF and PKCE.

Yup, planning on expanding to add a PKCE and OIDC walkthroughs as well!

I really enjoyed the way you presented that, really helped me to focus while reading.

This looks great! I'll surely come back to it later.

How much of the process can be pushed to server side? (Sorry, I don't speak JS.)

Pretty much all of it! The JS in this walkthrough is all server-side. I tried to keep the JS itself simple so that someone unfamiliar with the language could have an easy time following the code.

It’s all server side. It’s written using express which is a web server framework built on top of nodejs

Just to clarify, this use case would be for internal code documentation rather than providing external walkthroughs for your users?

Well, both but I could only pay for it in the former case. For personal use I’d love the latter.

I'm working https://annotate.dev, a tool inspired by the Stripe documentation, to let anyone create step by step code walkthroughs. Here's a sample of a walkthrough you can create: https://annotate.dev/p/hello-world/learn-oauth-2-0-by-buildi...

Would love to hear any feedback thoughts!

This is a great app, especially in this age of AI code generation, I am already using it. Looking forward for features such as light mode and exportability among other things.

This seems like a cool idea but I'd have to see it in action for something I need to learn.

The first thing that jumps to mind is that I want to click on a piece of code and see the explanation for it. It seems that it only goes in the other direction. I could imagine looking at the code and understanding most of it and just wanting to understand part of it.

I could anticipate an issue though - it could be many-to-one from explanation to code. The UI for that would be complicated.

If you’ve not seen it, there’s a vscode extension called CodeTour that does something similar, could be good inspiration (or maybe you already do better!)

It's the first time I've heard of CodeTour, I'm really impressed from what I've seen thus far. Digging a bit deeper now, thanks for sharing!

This is great idea!

I actually have several potential improvement ideas.

1. Put the walkthrough it in a graph, or a minimap to see the whole picture easily? Or in a https://c4model.com/ visualization 2. Why not make clickable code references visually stand out? 3. Make a VScode extension for it

Thanks for taking a look and sharing feedback!

I'm not familiar with the c4 model, I'll need to investigate.

> Why not make clickable code references visually stand out

Is the goal here that you want to know that a specific text block annotates a part of the code?

> Make a VScode extension for it

I think I will! I need to noodle a bit on the user experience here

This is awesome!! I can see a major use case for enterprise or government but along with that would come the desire for on-prem. Any chances of that happening?

Thanks for checking it out!

I'd be happy to build and support an on-prem solution, but I'd a need commitment from an enterprise/government org. If that's something you're interested in, shoot me an email at alex@annotate.dev!

This is a really clever idea, and worked great on mobile as well. Is there a way to choose to display the code window underneath the documentation instead of on top?

Thanks for the kind words!

Not currently, can you elaborate why you'd want to the code window at the bottom?

I think I'd also like an option for the code window to be at the bottom. Generally when I'm reading blogs/articles on my phone I put the line of text I'm reading at the top of my screen.

The code being up the top felt like it was in the way of where I was naturally expecting the line I wanted to read was.

Also, I think this is great! Definitely something I'd want for my documentation.

This is great feedback, not something I initially considered. I've add it to my todo list

This is really cool. I wish there was something like that when I learned to code.

That's a cool idea!

Great idea! What did you use for designing the UI?

Thank you for checking it out!

I use Figma to get a proof of concept of how I want things laid out. From there it's more tinkering at the code level.

can this be self-hosted?

Not yet, what use case do you have in mind for self hosting?

I am sure folks at /r/selfhosted would love it.