Hacker News Reader

Comment by tip_of_the_hat | Hacker News Reader

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!

View on HN

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.

Reply on news.ycombinator.com