3 ms·

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

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.

spartanatreyu 6y ago
TL;DR The Grand Unified Theory of Documentation: https://documentation.divio.com/ 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 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.
- deleted 6y ago
  [deleted]
- tomatohs 6y ago
  Wish this were higher up; lots of discussion here assumes this is for reference documentation when it's only relevant for usage docs.
modernlearner 6y ago
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.

spartanatreyu 6y ago

TL;DR The Grand Unified Theory of Documentation: https://documentation.divio.com/ 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 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.

deleted 6y ago
[deleted]
tomatohs 6y ago
Wish this were higher up; lots of discussion here assumes this is for reference documentation when it's only relevant for usage docs.

modernlearner 6y ago

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.