I would like a tool that does something similar to this but on a more ad-hoc basis. i.e. to track my own explorations and understanding for fixing a given problem in a code base.
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.
> I would like a tool that does something similar to this but on a more ad-hoc basis. i.e. to track my own explorations and understanding for fixing a given problem in a code base.
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.
One common theme we found between our onboarding experiences is that it was often difficult to start working on a project. Typically we went through many rounds of discussions to actually understand the flow of the code. Tools like Dropbox Paper and Confluence are great at communicating high-level specifications for engineers, but fail to capture nuances needed for new engineers to continue developing.
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:
Sorry about that! You shouldn't need to be logged in to Github to view a tutorial on a public repo. Can you try again now? We've fixed this and just pushed a fix!
Hi, I only checked it out on my phone for a minute so please don't take my comments too serious.
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.
Sorry about that! You shouldn't need to be logged in to Github to view a tutorial on a public repo. Can you try again now? We've fixed this and just pushed a fix!
Edit: We are getting rate limited by GitHub - we are moving our example over to Gitlab to avoid this.
I could see this being helpful for potentially navigating a large codebase, especially for newer employees. could help integrate them into the team / project much faster.
> No more inconsistent documentation scattered throghout your codebase. Create tutorials that highlight the right way to do things and are accessible to all.
FYI “throughout” is misspelled.
This looks really promising. I’m excited to give it a try at my workplace.
Nice tool, I like it.
Are there any plans to release some kind of self hosted / licensed version?
We do have an internal GitLab/Bitbucket server which is not accessible from outside.
We are planning on releasing a self-hosted solution! We'd love to get in touch to make sure it fills your needs. Could you email us at usecodeflow@gmail.com?
Still asking for Github permissions for me (to view a demo / example) - without it I have no idea what this is. Even screenshots or something there would give an idea.
Sorry about that! You shouldn't need to be logged in to Github to view a tutorial on a public repo. Can you try again now? We've fixed this and just pushed a fix!
the best way to ramp up on a codebase is to simply follow the critical path and draw an execution diagram of the entire critical path. tools like these are gimmicks.
My experience with large codebases is it is hard to follow a critical path, especially with multiple things running in parallel. This leads to lots of back and forth between the new engineer and the rest of his team, taking up time for both parties -- which is why we created Codeflow.
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
This looks interesting, but how much does it cost? I don't want to start using something and then hit the "please pay us now" screen without first knowing how much I'll owe.
Codeflow will remain free for use on repos owned by small teams or individuals. If you had a larger use case in mind, we’d be happy to discuss more via email: usecodeflow@gmail.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.