Document your code just by hitting “record” | Hacker News Reader

Document your code just by hitting “record”

paircast.io

211 pointstomatohs97 comments

I hope people do not use this to document their code for others. I code for a living and I cannot see screens or watch videos. Maybe to keep a diary, sure, but nothing can beat written text in terms of accessibility.

Paircast automatically transcribe the video's audio to text.

Yes, but then you only have the video's audio but miss out on the actual code being written, meaning you lose a lot of context.

It also records the code being written.

If the text-only experience is good enough, then why bother with encoding and storing a video?

Books are pretty good, why bother with movies?

Although I agree with you, this comment is missing the mark. Books and films are two fundamentally different mediums and have two different audiences, while this is more about supplementing the text version of something with audio/video.

I think that an audio (or video) version would be superior, but more because, assuming there are captions, the audio might be able to describe something beyond the code alone more easily than typing out a note would.

It takes lots and lots of effort to turns books into movies and vice versa.

You don't just take a transcript of the dialogue in the movie to make a book.

It claims you can git checkout code from any point of the lecture/cast

The git commit hash is included at the top of every diff in the transcript. You can `git checkout [the hash]` to get the code at that point.

Ok, that’s actually awesome!

+1. I do a lot of videos, especially now that COVID has put the kibosh on in-person conferences and everything is pre-recorded. I usually need 3 takes to do a decent talk recording and that assumes substantial prep to lay out the story line. Anything less is a meandering mess.

It's way easier just to write a decent README.md.

Why not both?

What does the video add that the readme doesn't do?

Segues to sponsors and screamed content as attempts to keep your attention and to prevent you from falling asleep.

Honest response:

Wonderful documentation is hard to beat from my learning perspective, but I find that level of quality is more rare.

Therefore, I learn better by watching something materialize on video at ~3x speed and often without any speaking.

I think it simply boils down to my level of trust that this person didn’t accidentally omit anything from their article or blog post or whatever and what I see on the screen is what I get. Now, that doesn’t fix when tools change etc, but videos instill a higher level of trust that, if I follow these steps, I will produce this output.

Majority of coders can see the screen so as a mvp this would be great for those users.

No joke, I saw a comment in my code base literally yesterday written from a week ago. I said this is crap and it's taking me more than 5seconds to understand and I ended up simply changing some variable names and refactor the function. It took maybe 2 minutes to do but now I don't need a comment and it's cleaner code for future changes. (It's in a file we are actively working on and WILL change)

tl;dr: Refactor not comment

Ideally the code should describe what you are doing and how you are doing it.

You might need comments to describe why you are doing something. And you definitely need comments for why you are _not_ doing something else.

in today's world - you either watch a pre-recorded video or a live zoom call. there's no third option.

Doesn’t this depend on how well the videos are transcribed? I imagine for some people it’s way easier and faster to record a video than to type.

Okay as a tool to create tutorials or lessons this is pretty cool. It was not clear from the title and home page that this is the target but looking at the demo video makes this clear.

As a tool to actually document code however as the title suggests this would be a terrible, terrible idea. No code comments or commit messages except a link to a video hosted on a website that may become broken or simply shut down at any time in the future? No thanks. What if I take 2 hours to write 10 lines of code, do I expect people who come after me to watch a 2 hour long video to understand what I was doing? It would also make public a mental process that may be messy, and maybe cause a similar effect to being watched over your shoulder while you code. Not to mention the usual problems of video like low consumption speed, linearity, and non-searchability.

This is an enhancement to video tutorials, not a replacement for documentation. Looks very cool but this is not a get-out-of-jail-free card to avoid writing documentation as the title here seems to imply.

The idea isn't to avoid writing documentation, it's to create any documentation where there was none. It's inspired by this quote from a GitHub survey.

> 93 percent of the respondents noted that incomplete or outdated documentation is a pervasive problem, but 60 percent say they rarely or never contribute to documentation.

The bet is that it's easier to talk about coding while you do it than sit down and write the docs.

https://opensourcesurvey.org/2017/

In my opinion, "creating a coding tutorial" and "creating/updating documentation" are two things that seem conflated here when they're very different workflows.

I wouldn't ever prefer to create a video tutorial rather than just write out documentation. It's just too far from my workflow (maybe that's just me).

I can, however, see how something like this would be extremely valuable to people who are instructing others on how to write code (DevX, bootcamp instructors, people who do video coding tutorials). I think that "Document your code just by hitting 'record'" is overselling that value though.

TL;DR The Grand Unified Theory of Documentation: https://documentation.divio.com/

There's a lot that is mistakenly conflated as "documentation".

Sometimes I would know enough about a topic except for one little thing and would look to the documentation. I only needed information on that one little thing to be productive, but I'd get stuck reading someone's entire backstory, trying to skim and find the one useful line in a random example to help me.

Other times, I would find documentation and struggle to follow it in practice until I came to the conclusion that I would need to read the whole thing in its entirety to become productive. I would either have to block out some time to learn it all or go with a completely different solution.

I used to think projects that claimed to be documented either fit into two groups:

1. Good documentation: I can find what I'm looking for

2. Bad documentation: I can't find what I'm looking for

My eyes were opened when I read something that I have since committed to memory: https://documentation.divio.com

There isn't just good documentation and bad documentation, there are 4 different kinds of documentation for distinct types of information delivery: Tutorials, How-To Guides, Explanations, and finally Reference.

Now I consider documentation good or bad based on if it contains all 4 kinds of documentation.

Wish this were higher up; lots of discussion here assumes this is for reference documentation when it's only relevant for usage docs.

They're definitely two different workflows and for every day work, creating a video tutorial or a "codelab" is a lot more work than just writing some Markdown text in a README.

Creating incentives within a work environment to write better documentation is easier than trying to record video tutorials.

I agree it looks like a good tool for producing instructional videos.

It's definitely easier to talk about coding while you do it.

I make heavy use of voice notes myself.

A transcription of those voice notes isn't something I've found useful. I have one, since it's just a little script but there is a very good reason that "stream of consciousness writing" isn't how we do ... anything.

I'm very curious to see how this can be used but I'm not immediately convinced, you generate commit comments while you write code, documentation is a completely separate thing.

A stream of comments on the why of some parts of code, for people who screencasted the development, would be useful. You could reorganize that stuff and get a really nice set of data about the reasons for code evolution.

That's not user facing documentation however, and providing design docs as documention, especially as stream of consciousness design comments seems like it might not be what people expect or want.

I have done tech writing for a living, and enjoy writing. However, documentation can feels more subjective than code when it comes to getting a PR accepted on an OS project.

For example, I’ve got an open PR overhauling CRACO’s (create react app configuration override) documentation right now.

It’s a fair amount of work and hard to measure the impact.

There less ways to define “correct” when it comes to docs than bug fixes or feature enhancements.

I get why docs languish. Anything to make the process easier is probably a good thing.

about.... 15 years ago, I had an idea for allowing embedding of multimedia files with commits. svn was the thing at the time, and eclipse and netbeans were the dominant players. I had 0 idea about how to build something like that, but it seemed useful. still does. even now, we end up, sometimes, writing comments in pull requests which may correspond to particular lines in particular files, but we can't easily connect anything else. Perhaps some metadata format for comments could be defined and IDE plugins could make fetch the media... ?

OFTEN I want some form of "stream of consciousness" thoughts associated with code - "spoke with Titus and Jen about this, and the loop needs to be broken up because foobar...". most of the time if I embed comments like that, someone blocks a PR or just rips them out in the name of "cleanliness", then 3 years later people are wondering "why was this done this way?" Links to tickets can help, but ... ticket trackers change - a reference to Trello card GKO-826 does no good when the project moved off Trello 2 years ago.

Perhaps long term there's no good way to deal with any of this...?

  // @medianote ./20180902121352.mp3
  while (x<users.length) { 
  // ...
  }

button in IDE to record audio note, and have it stored under ./.media relative folder... ?

> Links to tickets can help, but ... ticket trackers change - a reference to Trello card GKO-826 does no good when the project moved off Trello 2 years ago.

Keeping links working within your organization is really important, and I wish places prioritized it more. Our code often links to our bug tracker, and I'm thankful that my current employer does value this and these links work even when they are decades old.

This is why I keep coming back to the idea that we need tools that keep their data serialized in the repo itself. I talking about issue tracking, project planning, documentation like github wikis or confluence, all that stuff.

There are quite a few problems to solve to support this that I haven't worked out properly, otherwise I'd be building it.

For example, where do you keep your backlog? How do issues and issue statuses get stored? How do you report on open tickets and progress if the state is scattered across a bunch of different branches?

I've been playing around in my head with tangential feature. I run into situations where I must make some assumptions about a codebase and its context which aren't translated into the type system. I add comments to remind readers whenever I feel like an assumption should be stressed.

However assumptions change with time. I'd like to be able to cross reference all the places in the code base where certain assumption was made to a readme section with necessary details and background. In my ideal world IDE would resolve these links and made them easier to maintain.

_EDIT: word order_

This is actually one of the more advanced features.

Since Paircast works with git, we can link each LOC to the point in the video where it was created. Take a look at the `git blame` and the Paircast links in the sidebar.

https://github.com/haxordx/paircast-demo-1/blame/main/main.j...

I would have loved to store the media within the git repo that Paircast creates, but unfortunately that requires `git-lfs` which developers absolutely hate.

Given that the audio files don't need to change too often, is storing them in plain git an option?

Hadn't thought of storing only audio, that would definitely be possible, but doesn't seem very useful.

> thoughts associated with code - "spoke with Titus and Jen about this, and the loop needs to be broken up because foobar...". most of the time if I embed comments like that, someone blocks a PR or just rips them out in the name of "cleanliness", then 3 years later people are wondering "why was this done this way?"

I really hate it when people do this. The commit message should be all about the why (the diff already tells me the what), getting rid of it means removing the only useful bit of info from the commit message.

There's code comments and commit messages. I was referring to code comments, not messages. I am on some projects where others are really strict about "no superfluous comments". Yet... the thing that's helped most when looking at 5-10 year old code is someone's multi-line comment about what decision led to something (sometimes with decision maker names, dates, etc) and some reasoning. None of that is remotely discoverable in things like confluence (at least in any project I've worked on in the last 10 years or so).

It's crazy that businesses that are built on top of code spend hours in meetings to come to a decision that isn't documented anywhere for people to see 2 years down the line. These are team leads who have worked for close to a decade. They must realize the value in documentation by this point.

git blame can bring up relevant commits.

There's bound to be some way to insert audio in an org-file at this point, surely?

Seems a bit redundant to store an audio file in version control which essentially represents a comment...

Why not just use a "speech-to-text" software to add documentation?

maybe. I used audio as an example, and it was on my mind years ago when screen capture was far less common. Audio/screenshots/movies - Webex snippets, etc.

Also, sometimes audio can let you more easily capture nuance/tone that you don't get in text alone. And ... some people just are good at talking through their thought process.

That's an awful reason to block a PR. I've been doing code review for the past 6+ years and I'm on the other side, I often ask for better, and longer code comments, for the reason you highlighted, 5 years later (or even months later) that long comment will save us hours

You're in the minority of people I've worked with in the last few years who make those sorts of decisions.

When I can, I try to keep some parallel /docs files with some relatively up to date tech notes close to the code. Jira/confluence/etc might also have info, but the docs that are connected in the same repo have a different level of usefulness for some things.

In the same timescales I was thinking the same thing, but in particular recording the conversation between pair programmers.

OneNote had (has?) a mode where you could click on sections of a meeting note and hear the audio from the time the text was written.

Extend that to an IDE and every time you found yourself saying “what were they thinking when they wrote this?” you could listen in on the conversation and find out.

I tried this and it was really smooth: Good experience from installation to upload and reviewing the cast!

Things I really liked:

1) the electron app records my voice and screen and then gets transcribed with some API in the back: as an English speaker with a thiccc accent this worked very well

2) git all the things: as you type and you record your screen, all changes are staged and time-stamped so you can quickly grep the result and find when you said or typed certain things. That is major useful for code-reviewing so you can go back during your pair session and immediately find things.

My only fear is that all this data is stored somewhere outside of my realm, and if it records personally identifiable data of some sorts from my screen, I never will feel like I will be able to make sure the recordings/transcripts are gone-gone.

Good job Ian!

Is the pricing structure documented somewhere and did I just miss it? If not, I would encourage the author (if he sees this) to please publish it, as I like to know how much something might cost me before making it part of my set of tools.

Header has been updated with pricing. http://paircast.io/pricing.

Just a quick heads up: I'm a weirdo with WebRTC disabled by default which broke app.paircast.io for me. Because the pricing page embeds pricing from app.paircast.io, that failed for me, too, until I enabled WebRTC.

I like what has been done here and this is a problem I am actively thinking of as I am creating my own attempt at teaching how to code [1].

Would it be possible to use an IDE, like VS Code, to replay git and video? The author's video could be a hovering head with video controls that are tied into git (repository contents being shown by the said IDE).

The comments here might seem demotivating but I too feel that video is not the best delivery mechanism for code - the IDE is. You have nicely wrapped Git with video timestamps. I feel that using video to show the code is poor UX.

[1] https://github.com/brainless/solvex/tree/develop

Edit: sentence structure in para 2.

I think the audience here is missing that the code diffs are included in the markdown below, probably because you need to scroll to see them. See around 3:38: https://app.paircast.io/replay/fa41d539-aea0-4d62-a192-3cd77...

Because the Paircast git commits include a timestamped link to the video, using something like gitlens in VS Code would allow you to click from code to video. https://github.com/eamodio/vscode-gitlens#autolink-settings

Yes I noticed that and the diffs are really done well. I feel your product has a great start but as a founder myself, I would suggest you to take the comments here, from everyone, in a positive spirit. I understand how negative it might feel, but if you want the best UX for teachers and students, then integrating with filesystem/git/IDE is really going to make a dent in the problem space. IMHO.

Unfortunately I can not test the link as it needs me to download the app and I am on Linux - that is my primary/work OS.

Video is a great additional tool for the communication of ideas or learning. But it is an additional tool. I much, much prefer the written word for communicating ideas about code and technical concepts. I cannot stand videos about programming topics, and I'm frustrated by how frequently they're the definitive source on a topic. They do not feel as effective for me.

While I understand why others might like videos, I really hope they stop catching on so hard. Especially with a facecam.

One of the beauties of programming is that I can function with a bunch of fellow ugly nerds who don't make me show my ugly face just to get work done.

I feel the same way which is why we're building this. Paircast outputs a markdown tutorial for anyone who's making coding videos. Facecam (and using the product) is optional.

Sorry I must have gotten pretty confused. The tool is mainly responsible for going video -> markdown rather than being a video solution?

That seems better but putting effort into written communication is why I like it more than video anyways.

It's a three-way link between video, git commits, and markdown. You can edit the markdown on the cast as well. None of this is explained as well as it should be.

@op very cool, reminds me of ascicast. Random example: https://asciinema.org/a/237460

Personally when I do a recording I have constant mistakes. It would be nice if in editing, I could easily delete pieces based on the transcript, and it would automatically delete the corresponding part of the video. So I could just delete that part in the middle where I mistyped and had to spent 2 minutes debugging, instead of having to stop and start over.

Yes! Asciinema and similar tools were huge inspirations. Editing the video from transcript (like Descript) is certainly a feature for the future. For now, you can use "highlights" to isolate the "the good parts." See this image: https://i.imgur.com/wBLPyAI.png

I am not a native english speaker but transkript is not that good. I can change the script later thats not a big NO for me.

I have tried the free public cast version. It works well. Now i want to delete that demo try cast. Delete buttons not responding.

Developer Console Output is below: Failed to load resource: the server responded with a status of 500 (Internal Server Error) production.min.js:1 Uncaught (in promise) CloudError: Endpoint (`deleteHighlight`) responded with an error (or the request failed). at Object.exec (https://app.paircast.io/min/production.min.js:1:1581269) at https://app.paircast.io/min/production.min.js:1:1580713 at new Promise (<anonymous>) at Object.toPromise (https://app.paircast.io/min/production.min.js:1:1580681) at Object.then (https://app.paircast.io/min/production.min.js:1:1580465)

Response Body: Internal Server Error

video is too small to read and I don't see how to enlarge

Tiny video and you can't full screen. Why not use YouTube?

Not using YouTube is often the right choice. Blocking browser video controls is almost never the right choice. (Rare exceptions when you're using video as a substitute for animation, but even then, don't block right-click controls.)

We're not explicitly blocking video controls. I think this is due to the iframe embed.

Ah, interesting. Looks like the video controls become available once the video is playing, just not before it starts.

This is probably because it appears in an iframe. Try the full link here: https://app.paircast.io/replay/fa41d539-aea0-4d62-a192-3cd77...

Right click -> full screen

That isn't an option in Chrome on macOS

Here's an example of readme output: https://gist.github.com/ianjennings/15a65d05f1112e6b9cfc31ca...

I looked at the pricing table and apparently you won't own the output?

Is there a thing where you can show your code running on the left(say a GUI) and then on the right it shows a high overview(file names/related files/method calls in a visual way like uml) and highlights lines of code as it executes.

This could be helpful for code reviews imo regarding context transfer. I usually pick the easy stuff eg. syntax/more efficient code as opposed to the bigger actual context part depending on how big the review is/how familiar I am with that area.

damn, this is very close to an idea I had some months ago (but better) that I decided to drop in favor of others. I think I am going to be using this in the next week.

I had a simliar idea a year ago, and did a proof of concept with some script and OBS. Glad to see it moving to reality, there's lots of rooms to grow for this idea. Got the idea after watching a coding session from some of the core golang devs.

I used an earlier version of this to run some tests for AWS usability and for PyTorch usability. I like the product a lot.

Here you can click on a line of code and be brought to that point in the video: https://github.com/haxordx/paircast-demo-1/blame/main/main.j...

I watched the video and did not understand the product. Is this supposed to be some way to make me watch a video that also documents how the code was written and how it is meant to work?

The video would be distracting from the mental model I have built of how the calls stack and can get stale pretty quickly.

Being able to automatically translate the texts would be a killer feature. It's probably outside of the scope for this product but language is quite a significant barrier for at least 80% of world population that doesn't speak English.

I often just do one fps screen captures of my coding sessions and it,s helpful to review

this is a really cool idea, hope it gets traction

This sorts of videos would be much better if you could record keystrokes instead of the video; since coding is mostly just text based (and would be nice if you could copy straight from the video somehow).

The full code samples appear in the transcript below. Try the fullscreen version. https://app.paircast.io/replay/fa41d539-aea0-4d62-a192-3cd77...

This looks really useful for leaning a new language or framework. The basic idea of syncing commits with video timestamps and adding speech to text is brilliant.

I hope you make traction with the new tutorial format.

Haha, this guy build awesome stuff. But when I reading all the comment, most of them give a straight feedback . ouuchhh

@tomatohs If it's not a secret, what do you use for audio to text conversion?

I watched this and I have somehow the feeling that it solves the broblem that does not even exists ?

documenting code - do not use video! Do you even document it while writing, that does not make sense because the video will be invalid and old in 2 hours

teaching -nope, just give us the working code

I wish I could see something on that video. For an app focusing on delivering screencasts, you are dangerously bad at delivering screencasts.

Recorded this yesterday pretty quickly and submitted it here not thinking much of it. Turned the iframe into a CTA.

Even in fullscreen, this is barely readable. This video is prime example of why using videos is probably a bad idea when the focus is on text. It is so frustrating to see a screen where most of the content is impossible to make out.

Pro-tip: don't record your demos on a 4k monitor setup or whatever this is. I just measured, and your IDE's font shows characters as 6 pixels high on my 1920x1080 monitor. Did you watch your recording?

Video at this resolution is a common use case, so feedback like this is helpful. No developer wants to reduce their screen resolution to record a screencast, it totally breaks flow.

There is a huge focus on text, which is why the full markdown transcript is included.

cool idea, but no support for linux?

Judging by the binary size it's probably electron, so I can't see why.

“Everything should be as simple as possible, but no simpler.” -Albert Einstein

This is awesome !!

Could become a killer app for Mac TouchBar

Reply on news.ycombinator.com