How viable is this idea?

Question

As codebase gets large it becomes painful to grasp and work on. Now with remote culture the chances of pulling coworker to side and asking quick questions seem to be out of the window.I was thinking gee i'd have loved if the senior dev in my company just made a video explaining throughly how everything is setup, what does this do and why?I've not fully thought out this, but I was thinking what if there was a systematic way a company could be brought in to document and then create tutorials one the code which then can be used by new hires or even devs who are new to the area.Questions the videos could address...- how is this setup? where does the data come from and where does it go..- what does this variable do?- why are we doing this?sadly wont be able to answer...i want to do xyz, where should i look?but still I feel there is clear value in video tour of codebase, like a video tour of house and how all is connected.

GianFabien · Accepted Answer

It's a great idea. You would need to plan this carefully. Most senior devs probably couldn't effectively communicate all those points without a pre-crafted plan. Effectively you would need to fuse technical writing skills with script writing skills. That on its own would be considerable value-add.

Minor49er · Answer

Unless you tied it to the exact areas of the codebase somehow, finding specific information about the code in video form would be hard.
Plus, for myself, I don't know how many times I've seen a piece of cryptic code written by some prodigy who left the company years ago. It would take a lot of effort to get documentation around these scenarios.
Instead, it would be easier to get a company to get on board with adopting proactive documentation practices. This doesn't necessarily mean explicitly writing technical documentation, either. It can be implicit.
Some companies that I worked for in the past would have policies around how work would be completed. A big thing they did would ensure that all of our work had tickets associated with them and that all branches were named after the tickets. This made it trivial to blame a line of code and start digging into not just who made it or when, but also why. I could see what other tickets were related to it to find out a lot of valuable contextual information, sometimes even for code that was implemented years before I showed up.

ggm · Answer

I wrote a set of PPTX to induct new hires into our core concepts, values, specific language uses. It helped a lot with a bunch of recent "what do you guys mean"I talk them. It hadn't occurred to me, to video the talk that goes with them, but that actually makes sense

yonl · Answer

In our org we have video tutorial for env setup, how to use tools etc. Used to use native video recorder + notion. Now we use https://www.letsflyby.com/. It's a general purpose recording and annotation tool (which helps bookmarking a section of the video of the codebase).

auslegung · Answer

iirc there&rsquo;s an extension for a VS code that facilitates this kind of a thing. ie, it doesn&rsquo;t do what you are talking about, but it would allow you to record a code walk-through, complete with audio and I think a screen recording or something like that.One way to partially test the viability of your idea is to see who is using this tool and how, or other tools like it

codingdave · Answer

The main argument I hear against extensive documentation is that the codebase changes too quickly to make it worth the effort. I cannot see video as being any better in this regard - it takes more effort to create and more time to consume. Seems like it would be a large effort just to get around the concern of asking quick questions remotely.

enchiridion · Answer

Not exactly the same, but https://paircast.io/ is in the same vein.

dalewebb · Answer

There was a product listed on HN a while ago that tackled the problem with the solution you described. I can't remember what it's called though...

dyeje · Answer

This is the age old question of how do you keep the docs up to date with the code.