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.
+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.
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.
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.
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)
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.
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.
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
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.
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... ?
> 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.
> 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?
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.
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.
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 would have loved to store the media within the git repo that Paircast creates, but unfortunately that requires `git-lfs` which developers absolutely hate.
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.
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.
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.
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.
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.
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.
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.
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
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.)
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 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.
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).
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.
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
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.
