Show HN: StoryTime – Create stories about your code instead of documentation | Hacker News Reader

Show HN: StoryTime – Create stories about your code instead of documentation

storytime.dev

193 pointsvidoss67 comments

I 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-aam8Mq7LwfZ...

2. Advance with spacebar: https://sequoia.makes.software/composer-talk/#/7/1

I describe the process here: https://sequoia.makes.software/techniques-to-avoid-live-codi...

Thanks for sharing. This gives me some target use case to work towards.

Everything 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 :(

private 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

Subscribed... :)

Another Bitbucket vote here. Subscribed.

Innovative 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.

I 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.

"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!)

The links at the bottom look like ads. I unconsciously ignored them until I visited the page again.

Hi, OP here. Would love to get some feedback from HN community.

so, 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/

A 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)

I 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.)

Good point. Will add keyboard support.

I 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.

Thanks. There is step forward / backward icons next to play. Maybe should just kill play?

That's my feeling yes, but I would check with other people, too!

Not 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.

For me, this issue is made worse by the fact that the text boxes can pop up basically anywhere... More than once in watching the first story, I only just located a new text box just as it was disappearing, and I had no hope of reading it.

ya, starting to think play is more distracting than helping.

Can 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.

Noted. Will do.

This 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?

Current plan is to make this available for free to public repos. Will be adding an app in github marketplace for private repos. Code will be open sourced after some cleanup.

Glad to hear it, looking forward to seeing it.

It 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.

Even on a small monitor I'm missing things because my eyes have to check two different places to see if they changed.

+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.

Agree. 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.

+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.

This 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.

Great feedback. Moving this line by line to my TODO. Thanks again.

btw, was the editor intuitive to use? I am thinking of adding product tour like popups on that page to get started.

I 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.

It 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.

The 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?

Thanks. Got similar feedback below as well. Will be moving this around.

The 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).

It 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.

Bug:

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.

This 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.

Thatz the idea. Current focus is to get as much feedback and implement them.

Great 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.

Thanks. 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.

Agreed, 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.

I 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).

Thanks. Will be spending time on accessibility.

In 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/ instead of https://storytime.dev/facebook/react/blob/master/

oops! noted.

Very 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.

Yes - 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.

Yeah 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.

The text snacks should show up next to the code. Not fixed to the bottom. It makes it hard to follow.

> Add memes and GIFs as you walk the code!

Cristo.

My whole repo:

https://gfycat.com/boilingoffensiveass-firstworldanarchists-...

lol

Code needs some memes and GIFs love :)

please be sarcasm

A really polished version of this could get you acquired by MS for a hundo million I feel.

Very 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.

This 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.

There 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.

Thanks. Will fix.

I 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.

may I see your documented side projects?

Unfortunately 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.

Reply on news.ycombinator.com