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