8 ms·
Show HN: StoryTime – Create stories about your code instead of documentation
- vidoss 7y agoHi, OP here. Would love to get some feedback from HN community.
- Lerc 7y agoThis is an excellent idea, it is a bit hard to use though. Some thoughts. I would prefer breakpoints to be disctinct from the current execution position. When thinking analogously to a debugger, Breakpoints indicate where the program should stop not where the program currently is, and consequently breakpoints can exist on multiple lines at once. I prefer a different graphic to indicate the active line. A line highlighted colour would be enough On my machine the area that is active for the 'line annotations' pop-up menu has no visual cue to say that it is there. It appears to crete a new 'line annotations' menu for each hover with the old menu lingering a short time before dissapearing, this looks quite odd. I have achieved multiple perminantly open 'line annotations' menus at the same time. It would be beneficial to have line ranges on annotations so you can higlight a block of code. Adding a new frame duplicating the current annotations would be good. Either that or have a way to declare the same annotation applies to multiple frames. Having the ability for an annotation to collapse a section of code to ... for within a single line or \n...\n for multi line collapse would let people focus on the code being explained.
- vidoss 7y agoGreat feedback. Moving this line by line to my TODO. Thanks again.
- vidoss 7y agobtw, was the editor intuitive to use? I am thinking of adding product tour like popups on that page to get started.
- Lerc 7y agoI figured it out easily enough, adding annotations and removing them was understandable enough, what the annotations did was a bit trickier but I think documentation would be better than a tour. A reference gallery showing what each one does would be ideal.
- billconan 7y agoso, what if my code has changed, will an old story matches the new code? a related project you might be interested in https://ourcodestories.com/ https://ourcodestories.com/
- vidoss 7y agoA copy of the code is stored in the DB. so its a snapshot of when you created the story. The annotations are react components added on top of the code. Soon you will be able to add custom components to annotate the code. (WIP)
- scott_s 7y agoI think that the default behavior should be that the user has to click or press the keyboard to progress the story. I started reading one of the stories, and it quickly went faster than I was processing. (Partially because I am unfamiliar with the source language and framework.)
- vidoss 7y agoGood point. Will add keyboard support.
- scott_s 7y agoI think that pause-by-default is more important than keyboard support. Put another way, I don't think that "play" as in "play a movie" is the right metaphor. I think that by default, the user should control progression forward and back, like scrolling through slides or flipping the pages of a book. Each person is going to want to linger on different steps for different periods of time, because we're all going to want to read different things along with what just changed.
- vidoss 7y agoThanks. There is step forward / backward icons next to play. Maybe should just kill play?
- scott_s 7y agoThat's my feeling yes, but I would check with other people, too!
- loco5niner 7y agoNot sure either way, but if you keep play, the user should be able to click both play and pause without moving their mouse. currently, play appears a couple inches to the left of pause.
- merlincorey 7y ago
- CamelCaseName 7y agoCan you make the textbox draggable? Or at least, reposition it near the center? It's a bit difficult to switch between reading code and reading the story.
- vidoss 7y agoNoted. Will do.
- MFLoon 7y agoThis is awesome, I've wanted a similar tool before. Is this open source or are you planning to commercialize? One bit of UX feedback - the modal with the commentary text is a bit low on the screen (at least on chrome on a 15 inch retina display), I think it would be better to have it higher up on the page, or possibly even aligned with the current line?
- cabaalis 7y agoIt may be a good idea to move the story text closer to the code. On a large monitor, I have to move my eyes quite a bit and it feels disconnected.
- azhenley 7y agoEven on a small monitor I'm missing things because my eyes have to check two different places to see if they changed.
- kaibee 7y ago+1 to this. Not sure if it was just that 'play' was too fast (I agree with the other comment about 'play' probably not being super useful here), but on my 27" 2560x1440 monitor, it took me a few slides to notice that there was even text at the bottom changing. I thought I was just supposed to read the comments.
- michaelmarion 7y agoAgree. Other than that, I really like this as a concept and can't wait to see where it goes from here. Will be keeping an eye on this for sure.
- vlucas 7y ago+1 - came here to say this. I love the idea, but the text block at the bottom of the screen and the corresponding code at the top left is a bit of a pain to go back and forth to with your eyes before the time runs out. It would be great if the text was much closer to the code.
- kstenerud 7y agoIt looks cool, but needs some mobile love. The screen gets very crowded on a phone, and feels very chaotic with things popping up and moving around. Touching the screen makes stuff scroll away from what the presenter intended, making it hard to figure out what's going on. Also, touching the "go back" button in the overlay triggers the phone's text selector, and seems to randomly bring you back to the very start of the presentation. It definitely needs a more visible way to lead your focus. It's hard to tell what you're supposed to be looking at.
- lkschubert8 7y agoThere is a typo on the landing page. StoryTime enables developers to easily simulate a debugger-like visuals to tell or read a story about pieces of code. There shouldn't be an "a" in front of debugger-like.
- vidoss 7y agoThanks. Will fix.
- tomcooks 7y ago> Add memes and GIFs as you walk the code! Cristo.
- duxup 7y agoMy whole repo: https://gfycat.com/boilingoffensiveass-firstworldanarchists-twincities-cfb https://gfycat.com/boilingoffensiveass-firstworldanarchists-...
- vidoss 7y agolol
- vidoss 7y agoCode needs some memes and GIFs love :)
- tighter_wires 7y agoplease be sarcasm
- scarejunba 7y agoIn the "Start Now" section, don't make me type something in if you have the default text. Right now, the text appears to be there but clearly we visit https://storytime.dev//blob/master/ https://storytime.dev//blob/master/ instead of https://storytime.dev/facebook/react/blob/master/ https://storytime.dev/facebook/react/blob/master/
- vidoss 7y agooops! noted.
- sequoia 7y agoI like this mode of explaining code things by slowly building up & talking through examples. I have been doing this in talks for a while to go over code bit by bit without live-coding. Examples: 1. click "present" & advance step by step to see transitions https://docs.google.com/presentation/d/1KVMwffTe-aam8Mq7LwfZzXwtlcy-VRHrBPk20x47_zk/edit?usp=sharing https://docs.google.com/presentation/d/1KVMwffTe-aam8Mq7LwfZ... 2. Advance with spacebar: https://sequoia.makes.software/composer-talk/#/7/1 https://sequoia.makes.software/composer-talk/#/7/1 I describe the process here: https://sequoia.makes.software/techniques-to-avoid-live-coding-part-1/#solution-2-code-quot-fade-ins-and-highlighting- https://sequoia.makes.software/techniques-to-avoid-live-codi...
- vidoss 7y agoThanks for sharing. This gives me some target use case to work towards.
- WrtCdEvrydy 7y agoEverything is about this is amazing except for 2 small things. 1) Not sure about private repos 2) I'm sure it doesn't work against bitbucket :(
- vidoss 7y agoprivate repo is in the works. Will be available as an app in github marketplace. Bitbuket and gitlab support coming soon. You can sign up to be notified here. https://storytime.dev/error/private https://storytime.dev/error/private
- WrtCdEvrydy 7y agoSubscribed... :)
- FascistDonut 7y agoAnother Bitbucket vote here. Subscribed.
- brnkrygs 7y agoVery interesting concept, thanks for sharing! Context and intent are critical when trying to understand code - this looks like a useful way to capture that. Merging the call stack display with the "debugger" is IMHO a particularly good idea. Out of curiosity: have you explored stories for code _over time_ at all? It might be useful to be able to build stories for a block of code that change from commit to commit as the code itself is mutated.
- vidoss 7y agoYes - easily able to do a diff with previous versions will be of great value when creating a story. Its in the feature list backlog. Will get on it soon.
- hsndmoose 7y agoYeah watching a section of code over time was what I thought this was going to be initially. That sounds really useful for sharing the story of "how we got here" to new devs.
- freehunter 7y agoI love this. This is how I document my side projects, I tend to write long stories to myself with chunks of code thrown in for clarity. This is much more elegant though.
- billconan 7y agomay I see your documented side projects?
- freehunter 7y agoUnfortunately none of my projects are open source and all of the documentation is in a physical notebook in my desk drawer. I’m just not a very good programmer so unless I explain to myself what this code does and why, I’m not likely to remember why I wrote it.
- Kiro 7y agoThe story text at the bottom is too far away from the code for me so I constantly need to "switch" between them and I don't have time to read both. Any reason for not putting it next to the code?
- vidoss 7y agoThanks. Got similar feedback below as well. Will be moving this around.
- FascistDonut 7y agoThe extra bounciness of the animation can be a bit distracting after a while too. Maybe have options for different animation styles (fade/none)? Also maybe positioning options for placing the text elsewhere (like top right middle).
- localhost 7y agoGreat work! I would love to see the comments inline next to the current highlighted lines vs. at the bottom of the screen. Also having this like watch windows would be awesome as well, especially if you can clearly see the different state transitions that happen.
- vidoss 7y agoThanks. Will add support for text next to line. There is a watch window available in the editor when creating story. Not used in this story.
- euph0ria 7y agoAgreed, on a big screen this was nearly unusable as it is now since I couldn't see which line was being affected at the same time as I was reading in the bottom of the screen.
- deleted 7y ago[deleted]
- simplify 7y agoThe links at the bottom look like ads. I unconsciously ignored them until I visited the page again.
- whoisjuan 7y agoThe text snacks should show up next to the code. Not fixed to the bottom. It makes it hard to follow.
- jedberg 7y agoThis is very cool. This is basically what I do when I'm making a presentation and talking about a block of code (albeit with a ton of work in Keynote to make it easy to follow). I think this is a really great way of explaining code, and I hope it this makes it easier for people to adopt.
- vidoss 7y agoThatz the idea. Current focus is to get as much feedback and implement them.
- KaoruAoiShiho 7y agoA really polished version of this could get you acquired by MS for a hundo million I feel.
- memco 7y agoI see a lot of comments on the usability improvements have already been surfaced, but I wanted to print out that one possibly invisible implication of this is that accessibility is an important aspect of these changes. I hope in addition to the visible changes of keyboard controls some attention. Is paid to ensure that the function of the tool is accessible to people with visual and motor impairments. Having good aria tags for descriptions, controls, politeness settings for changes and ensuring you using the right elements for the controls. The WAI and WCAG guidelines are both great resources to check for more info. (Sorry on mobile and check myself or easily get links).
- vidoss 7y agoThanks. Will be spending time on accessibility.
- broth 7y agoVery interesting concept. I found that the transitions were too quick for me to read the descriptions at the bottom of the page. It might be nice to set this transition interval or perhaps click to advance.
- dakom 7y agoInnovative ways to explain code is a great idea and I love the project. However, I don't love the name. These are explanations - not stories (unless we consider stories as being 100% exposition). There's no beat, scene, or chapter structure that pushes meaningful values back and forth in the face of conflict ("make it work" isn't a meaningful value - since it's the obvious goal of every character here), no progression or character building, no subtext or sub-agendas, no sense of agency or suspense where the code might pursue something counter to its purpose... Feel like it's a bit of hijacking of "story" in order to make headlines, since "code explainer" isn't as sexy.
- LyndsySimon 7y agoI get where you're coming from, but "story" here seems more akin to a "user story" than literature. User stories have been used for quite a long time for both software architecture and establishing/informing QA and testing processes. This strikes me as user stories without the "user". It's the same concept at a different level of abstraction. A "code story" is to a unit test as a "user story" is to an integration test.
- dakom 7y ago"User stories" have the potential to be a bit different... or at least we can use our imagination to make it so. "As a first-class klutz I want to have my data synced without hitting a save button." Ok - benefit of the doubt: Once upon a time, Jane was on her way to an interview when she slips on a banana peel and breaks her phone. Since ProductX doesn't sync to the cloud - she doesn't know where the interview is and tries her best, from memory. Now she happens to have a fantastic memory but she's also dyslexic and the address she stumbles into is a drug den. Mistaking her for a client and her thinking she's getting a job offer, she accepts a deal and walks off with $10MM of drugs. Now the they're after her - terrified and panicked and not wanting to rely on their forgiving nature, she uses her tech skills and the cash to forge a new identity and moves to another country to found a startup - a competitor to ProductX that has cloud storage, ultimately putting ProductX out of business. She didn't need their product to land a job afterall. Happily ever after. Except for ProductX. So ProductX really should add a sync feature. > This strikes me as user stories without the "user" It strikes me as "code stories" without the story. They're literally just explaining the code. Glorified comments with a slick UI. That is useful though, I really do think it's a cool product - I often feel like comments take up a lot of screen real estate and sometimes want to go deeper with explanations. It is a great idea to move them out and make them more like a slideshow with even more opportunity to do so. User stories aren't stories either, they are feature requirements from a user's point of view. I feel like this is all the inverse of when we watch movies that have hackers. There's a craft to storytelling, there's a craft to programming, and we can't just assume that superficial similarity is enough. When a character in a movie types a bunch of garbage onto the screen, that isn't programming. When a software manager describes feature requirements from a user's perspective that's not a story. I think small children are pretty good at telling the difference since they consume stories voraciously... try reading them a book of "user stories" or "code stories" and see what happens. (I get that you're saying it's not a story in the literature sense - but that's my point, there is no other sense and these other things are hijacking the term. By "literature" what I really mean is any medium that can properly express a story - song, dance, etc. are all genuine, proven storytelling avenues too. The reason I jumped on here wasn't to be a downer - it's because I was super excited, I thought someone figured out a way to use code to tell stories! That would be awesome... Unfortunately that's not what's happening here and I was super disappointed. sorry!)
- lpellis 7y agoThis looks pretty cool. One thing I'd like to see that could make it really useful is oembed support, I'd love to be able to embed a sort of mini-tutorial on my own blog post.
- joshstrange 7y agoIt moves a little too fast for me to read the message (bottom of my screen) and then flick my eyes back up to the code and internalize what it's doing. I'd prefer speed controls at a minimum but really I just want to hit space/right-arrow to progress when I'm ready... Like a slideshow presentation.
- LyndsySimon 7y agoBug: It looks like you're hitting the `master` branch by default - GitHub allows you to set other branches as the default for the repository. Several of my repos have `primary` as the default branch and don't even have a `master` branch, which causes this to fail.