Show HN: Codeflow – Understand a codebase quicker with PowerPoint-like tutorials
usecodeflow.com
usecodeflow.com
I'll also admit that I had a hard time understanding exactly how it worked.
It wasn't completely clear for each 'slide' what code was being referred to, I think the highlighting of the code being explained needs to be much more defined or the dimming of surrounding code needs to be more pronounced.
I think it would also be better if there were markers directly in the code side of the window that you could hover over to highlight parts of the slide that are relevant. It would also be beneficial if it also worked the opposite way. i.e. when clicking on a marker in the slide, scroll to the relevant code.
I also think your datapipeline example doesn't really show the value of the tool. i.e. it seems like a very straightforward piece of code that could just be read directly.
How are you planning to keep the slide information in sync with the files on github as they change?
I may not be the target audience for this because I would like it to work with code on my local machine and would only publish if I wanted advice from another programmer and then I would push up my branch and provide a link to the codeflow.
We're changing the dimming of the non-highlighted code right now -- that's feedback that we've gotten before.
We're also looking into ways to embed code into the markdown, and scrolling to the relevant code is a particularly good idea.
I think a lot of the value comes from when you're not sure how to navigate the codebase, so I agree that the example doesn't show the total value of the code. In larger codebases that are harder to navigate, I expect these to be much more useful.
Right now, we save the ref of the commit the slide was created on, so it's possible that the code will go out of date, but the slides will always be in sync.
One niche we were exploring was remote teams. We saw that they generally resort to screensharing to explain code and thought that this may be a better, faster alternative.
Thanks again for the detailed feedback!
Is this more along the lines of what you were thinking? https://app.haxor.sh/replay/bc8262ca-9d5b-493a-af48-3d59e366...
This is my own project, Haxor, which is essentially screencasting for your getting-started experience.
Codeflow is our attempt at a solution. It allows engineers to easily build powerpoint-like tutorials, which focus on stepping through the code logically. We hope it can become a centralized repository of tutorials designed to capture an engineer's thought process and make ramp up more efficient.
Here's an example of a tutorial built using Codeflow:
https://usecodeflow.com/tutorials/view/aws-samples/data-pipe...
At this stage, we're hoping for feedback as we try to validate this approach. Any and all thoughts are appreciated.
Update: The rate limiting issues should be resolved.
I think I like the idea and you have some slick visuals on there. Unfortunately not really usable on small screens, but that's a comment issue with anything code related. In any case it might be helpful to see it embedded as widgets in documentation to explain code segments which explain how to use a library or framework as an alternative to annotating the code snippets and having explanations in copy below.
While playing around with it my initial issue was that I wasn't sure if it was going to "play" automatically or if I could control when I was ready to skip to the next step / explanation. The auto play really didn't work for me in the sense that it was either to quick or unexpected. I would prefer to control the pace myself, especially if it's about reading code where I might want to stop and ponder. I think I would like to simply click a next button, perhaps shown as an arrow next to the current "box". A back/previous button next to the restart button wouldn't be nice as well. Hopefully that wouldn't complicate the UI to much.
The next issue was related to my small viewport: I missed the pop-ups because it (at least on Chrome for Android) did not automatically scroll to the next one. I would consider that would be very helpful for longer code segments.
Hope this helps. Good luck and good job in any case.
Edit: We are getting rate limited by GitHub - we are moving our example over to Gitlab to avoid this.
EDIT 19:34 GMT-3: Now works without! http://shouldiblamecaching.com/
Absolutely not. I'll live without it. Thanks.
Update: The rate limiting issues should be resolved.
Disclaimer: I am the founder of http://codeflow.co. We have been around since 2014 and have got the name copyrighted around 2016.
FYI “throughout” is misspelled. This looks really promising. I’m excited to give it a try at my workplace.
Great idea on the screenshots! We are adding that in now.
I thought it was an open version of that.
However, if there is a better way to follow the critical path/best practices that you do follow to do so, I'd be glad to hear them!
Looking forward to any insights you may have, and thanks for the feedback