3 ms·
I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”
by hesdeadjim 5y ago
I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”.
I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons.
First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing and polishing documentation for hours. When the code inevitably changes, I can throw away the old video and spend another thirty minutes making a new one.
Second, I can demonstrate what the code does while offering instruction around it. If I likened it to anything, it’s like having a series of lectures to your code base rather than a textbook.
And lastly, it’s proven GREAT for on boarding a new engineer in the more complex aspects of the project. Because they can go and view thousands of PRs, 90% of which have video demonstrations or explanations, they can do a lot of self directed learning and not require nearly as much over the shoulder time with other engineers. When your team is spread across 12 hours of time zones, this is very useful.
This method isn’t a panacea, and we still keep written documentation when we need to provide a concise set of “how to’s” to other teams. But for the dev team, it’s been great.
- Strilanc 5y agoVideos are also better at transfering tacit knowledge. Stuff like little habits and workarounds people have that are important but which they don't realize need to be communicated. For example, creating a virtual environment for a python project instead of installing it globally. This is a crucial step for things to work well, but it's so common it might be left unstated.
- watwut 5y agoVideos are super easy to produce. They are also wastful to watch and difficult to find something in. So, our company creates videos, no one except new people watches them and everybody complains about lack of documentation.
- strokirk 5y agoThis is a great idea! I'm a visual learner, and better att speaking than writing, so this is probably something I should try to do more. I've only done it once so far, but I created a short video with Loom to demonstrate how a bug could be caused in the PR that fixed it. Searchability is probably what would suffer from this approach, and the fact that text is much easier to edit (both for succinctness and correctness).
- mattlondon 5y agoWith respect, you save time making 30 minute videos, but everyone else then wastes time watching your video looking for info. I prefer it if people just write it down so I can ctrl-f or find it in a web search and get what I need instead of sitting through your videos. For general "welcome to Team X!" onboarding or training though I agree that videos have benefits. But for day to day knowledge and docs I couldn't think of anything worse, although it seems to work for you and it is popular on YouTube for some things (e.g. Unity game dev content seems be be pretty much 100% video based - if I just need to know how to set up something in the UI like character rigging or wheel physics etc, I often have to sit through 30min videos to find the 15 seconds where they show what buttons to click etc - if it was on a web page I could just skip right to it)
- watwut 5y agoI prefer documents too. But the fact is, the choice is between nothing at all and videos.
- photojosh 5y agoI just love YouTube's automatic transcripts for this. Open, copy it into a text document so you can read it in a bigger window, then ctrl-f. You can skim it quickly to find the key point you're after. Sometimes things will be transcribed incorrectly but the surrounding context helps.