9 ms·
Show HN: Codeflow – Understand a codebase quicker with PowerPoint-like tutorials
- rj254 7y agoOne 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: https://usecodeflow.com/tutorials/view/aws-samples/data-pipeline-samples/tree/3be77b/ck6851rna00080vl88v57b9yi 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.
- elefantastisch 7y agoWhy do I need to grant access to my GitHub account to view a tutorial?
- rj254 7y agoSorry 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!
- aashj99 7y agoI'm one of the contributors. Happy to answer any questions/comments!
- bockris 7y agoI 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.
- aashj99 7y agoThanks for the detailed comment and feedback. 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!
- tomatohs 7y ago> 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. Is this more along the lines of what you were thinking? https://app.haxor.sh/replay/bc8262ca-9d5b-493a-af48-3d59e366b9b7 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.
- dkarras 7y agoStill 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.
- rj254 7y agoSorry about that - looks like we are getting rate limited by Github. We are moving our tutorial over to Gitlab to avoid this issue. Great idea on the screenshots! We are adding that in now.
- manibatra 7y agoIt would be great to view an example without granting access to Github account.
- rj254 7y agoSorry 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.
- kroltan 7y agoStill requires authorization for me. EDIT 19:34 GMT-3: Now works without! http://shouldiblamecaching.com/ http://shouldiblamecaching.com/
- rspoerri 7y agonot going to look at an example on some random website where i'm asked to enter any of my credentials.
- rj254 7y agoSorry 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!
- deleted 7y ago[deleted]
- Luke-py-walker 7y agoI wish I had this during my internship. My mentor was literally writing notes on a separate doc while I was walking through my code.
- aashj99 7y agoSame with me ;)
- yogi12 7y agoI 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.
- kevintb 7y agoEchoing everyone’s requests that asking for Github permissions is a bit extreme, but I’m very excited for this idea so please upload screenshots!
- deleted 7y ago[deleted]
- aashj99 7y agoJust added some screenshots to our landing page. Thanks for the feedback!
- shdc 7y agoYes. This reeks of desperation. Wanting to get whatever details or credentials you can from users to spam them later. Absolutely not. I'll live without it. Thanks.
- aashj99 7y agoTurns out we’re getting rate limited by GitHub, we’re working on fixing this so you can view an example without having to login. Sorry about that. Update: The rate limiting issues should be resolved.
- vidoss 7y agoNice. I did something very similar. See https://storytime.dev/ https://storytime.dev/
- aashj99 7y agoWow, just checked this out -- this looks really cool. I'd to love to connect to hear more of your thoughts.
- frederikb 7y agoHi, 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.
- big_chungus 7y agoThis 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.
- aashj99 7y agoCodeflow 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.
- big_chungus 7y agoThanks for the information.
- jeromebaek 7y agothe 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.
- aashj99 7y agoMy 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
- murukesh_s 7y agoHey, nice project, and congrats on launch. But have you considered renaming the project? especially with other projects with same/similar naming? https://www.getcodeflow.com/ https://www.getcodeflow.com/ http://codeflow.co/ http://codeflow.co/ Disclaimer: I am the founder of http://codeflow.co http://codeflow.co. We have been around since 2014 and have got the name copyrighted around 2016.
- randyrand 7y agoDo you mean registered trademark? I don’t think copyright would apply to a short name.
- murukesh_s 7y agoyes, thanks for correcting.
- trevyn 7y agoThere are no records for the search "codeflow" in USPTO TESS.
- murukesh_s 7y agoit's in: https://ipindiaonline.gov.in/tmrpublicsearch/frmmain.aspx https://ipindiaonline.gov.in/tmrpublicsearch/frmmain.aspx, try class 42.
- classicalcomplx 7y ago> 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.
- aashj99 7y agoSpelling is hard haha. Thanks for the feedback and let me know if you have any specific feature requests :)
- nojvek 7y agoFun fact: CodeFlow is Microsoft’s very widely used internal code review tool. (Things may be different after GitHub acquisition) I thought it was an open version of that.
- aashj99 7y agoHaha, we had no idea -- sorry about the confusion
- eftokay83 7y agoNice 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.
- rj254 7y agoWe 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?