
Show HN: StoryTime – Create stories about your code instead of documentation - vidoss
https://storytime.dev
======
sequoia
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...](https://docs.google.com/presentation/d/1KVMwffTe-
aam8Mq7LwfZzXwtlcy-VRHrBPk20x47_zk/edit?usp=sharing)

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-codi...](https://sequoia.makes.software/techniques-to-avoid-live-
coding-part-1/#solution-2-code-quot-fade-ins-and-highlighting-)

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

~~~
WrtCdEvrydy
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
:(

~~~
vidoss
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](https://storytime.dev/error/private)

~~~
WrtCdEvrydy
Subscribed... :)

~~~
FascistDonut
Another Bitbucket vote here. Subscribed.

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

~~~
LyndsySimon
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.

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

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

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

~~~
cabaalis
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.

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

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

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

~~~
FascistDonut
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).

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

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

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

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

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

~~~
vidoss
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.

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

~~~
vidoss
Thanks. Will be spending time on accessibility.

------
scarejunba
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/](https://storytime.dev//blob/master/)
instead of
[https://storytime.dev/facebook/react/blob/master/](https://storytime.dev/facebook/react/blob/master/)

~~~
vidoss
oops! noted.

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

~~~
hsndmoose
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.

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

------
tomcooks
> Add memes and GIFs as you walk the code!

Cristo.

~~~
duxup
My whole repo:

[https://gfycat.com/boilingoffensiveass-
firstworldanarchists-...](https://gfycat.com/boilingoffensiveass-
firstworldanarchists-twincities-cfb)

~~~
vidoss
lol

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

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

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

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

~~~
vidoss
Thanks. Will fix.

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

~~~
billconan
may I see your documented side projects?

~~~
freehunter
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.

