You probably have already noticed that nowadays it’s becoming fashionable online to share technical material via videos (eg YouTube.)
I somehow can understand the appeal of creating videos for sharing thoughts/news, esp b/c it takes way less time and focus compared to writing things (just hit the record button and go.)
But videos are.
👎 not index-able (at least locally)
👎 not searchable.
👎 not copy-paste friendly if at all.
👎 impossible to skim through.
👎 a major distraction from the train of thoughts.
IMO, in most cases, the more effective and impactful medium of technical comms is the written form: a Mastodon toot, a blog post, a gist, a Pastebin entry or even a Facebook post!
I agree to pretty much all the previous answer (text >>>> video), just adding what’s missing from my point of view:
Video can be fun. As irrelevant as this might seem at first, motivation is an important part of every learning process. If you can make the information easier to digest for some people, it can make their learning progress more efficient and effective.
“Being fun” can relate to literal jokes (which I like much less in text documentation), presentation style, atmosphere. It can also help to address more sensory modalities to support learning (like audio, colors, or sometimes people just like having a face explain things to them).
I also feel I need to focus much less to follow a video than I need to digest a technical documentation in text form. Yes, I might spend more time on the video to achieve the same understanding, but I can consume it in more situations. For example, when tired before going to bed, or while eating, I might still watch a video about something I’d like to learn, but rather not scroll through the corresponding docs.
Ideally, videos would be additional to clearly structured and comprehensive text docs. But as much as consumers are people, producers are, too. If they happen to prefer video for whatever reason, and don’t have the resources to do both, video is what you get.
It really depends on what’s being taught imo. If it’s something purely text-based like programming then sure, I absolutely would prefer reading an article to watching a video. For most tutorials though I think there’s benefit in seeing things done visually step by step. Most tools are visual, so learning stuff like 3D modelling or video editing through text can be difficult, but seeing someone do it in front of me makes everything click since I can see exactly what he did and don’t have to read between the steps.
even for visual programs, I absolutely despise the 10min videos for something that I only really care about 5 seconds of. If visual programs had the option of decent text tutorials (with screenshots) it’d be much easier to get into
Technical documentation of API, Language constructs, and usage (a la mandoc) should always have a standard-compliant (any widely accepted help manual format like mdbook or texi) text form licensed under the GNU Free Documentation License (FDL). This is to ensure that freedom 01 (“The freedom to study how the program works”) is not obstructed in any way.
Videos are tougher due to having a much wider arrange of factors. First off, you’d want to make your videos accessible (using subtitles, on-screen graphics and not just a narration all the way through, translation to other languages). You’d also want to be able to share that video among your peers without obstruction. Just having it be hosted to a proprietary mass-media site like YouTube will not be enough. I have doubts about the “hit record and magic happens” premise, videos are a lot more daunting than text formats if you don’t have the prerequisite equipment and skills beforehand.
If you really want to create videos, you should have a text alternative to the video or at least a technical summary of the video’s topics attached alongside the video so that you can leverage both text and video alongside each other.
I hate videos. I’d rather read a book with 500 pages than watch a video about anything. Actually, I don’t think I’ve ever watched a technical video in my whole life.
If it’s a YouTube video, it probably has been made to monetise, not to share tech material. So I usually avoid YouTube, because most of the time it’s not worth it.
I like written-form documentation, it means I don’t need to play audio in our shared space at work. It’s also a lot faster to find what I’m looking for with written docs than skipping through a video looking for the relevant bits.
Usually when I’m looking for docs, I find that the less time I need to spend in the material, the better. Videos are fixed length and don’t often come with a list of labelled timestamps.
I’m mostly in the pro-written word camp myself, but I have sought out video tutorials in cases where written docs seem to assume something I don’t know. When I’m learning something new, a written doc might have a 3-word throwaway clause like “… add a user and then…”. But I’ve never added a user and don’t know how. If it’s niche open-source software with a small dev team, this may not be covered in the docs either. I’ll go fishing for videos and just seeing that they go to a web-ui or config-file or whatever sets me on the path to figure out the rest myself.
That is to say, video content that shows someone doing a thing successfully often includes unspoken visual information that the author doesn’t necessarily value or even realize is being communicated. But the need to do the thing successfully on-screen involves documenting many small/easy factoids that can easily trip someone inexperienced up for hours.
I’m as annoyed as anyone when I want reference material and find only videos, and I generally prefer written tutorials as well. But sometimes a video tutorial is the thing that gets me oriented enough to understand the written worthy I wasn’t ready to process previously.
Edit: The ubiquity of video material probably has little to do with it’s usefulness though, and everything to do with how easy it is to monetize on YouTube.
I like Fireship style videos for a quick introduction to a subject, but I avoid videos if I quickly need to find something. Text is searchable and just a lot quicker in general.
Weirdly not many responses are talking about real workspace that much. While written docs are king, video has its own place. Recordings of technical meetings are very valuable and if spoken in english, tools like sharepoint are transcribing them, so you can search them via text. Most often those meetings material will never be written, so video is best second choice.
Demo videos are not “documentation.” They are “demos.”
If you want someone to repeat your steps, it should be code or CLI commands. You can write more descriptive text, but as soon as you reference pictures to show something, you’re introducing ambiguity that text/code can avoid.
UIs change faster than videos and screenshots, as you said, can’t be searched, and are generally less accessible than text.
The source files for documentation should also live side-by-side with the code in the repo. As soon as it goes anywhere else, it immediately goes out of date.
Video demos are nice, but they are not documentation.
Documentation is an ordered list of functions, routines, methodologies, and possibly fields, with a description in a human language (usually English) that follows technical writing standards, assumes nothing about use, and explains what the element is to be used for. It should also contain notes on deprecation, any necessary descriptions of why the program or API is implemented the way it is, descriptions of any expectations of the end user, and no unnecessary frills. They’re technical writing, as a rule.
Videos are for showing you how to get a common job done using the tool or API; they cannot be true docs. It’s great for jumping in, but as docs they would be absolutely unpalatable!
You are not logged in. However you can subscribe from another Fediverse account, for example Lemmy or Mastodon. To do this, paste the following into the search field of your instance: !programming@programming.dev
Welcome to the main community in programming.dev! Feel free to post anything relating to programming here!
Cross posting is strongly encouraged in the instance. If you feel your post or another person’s post makes sense in another community cross post into it.
Hope you enjoy the instance!
Rules
Rules
Follow the programming.dev instance rules
Keep content related to programming in some way
If you’re posting long videos try to add in some form of tldr for those who don’t want to watch videos
I agree to pretty much all the previous answer (text >>>> video), just adding what’s missing from my point of view:
Video can be fun. As irrelevant as this might seem at first, motivation is an important part of every learning process. If you can make the information easier to digest for some people, it can make their learning progress more efficient and effective.
“Being fun” can relate to literal jokes (which I like much less in text documentation), presentation style, atmosphere. It can also help to address more sensory modalities to support learning (like audio, colors, or sometimes people just like having a face explain things to them).
I also feel I need to focus much less to follow a video than I need to digest a technical documentation in text form. Yes, I might spend more time on the video to achieve the same understanding, but I can consume it in more situations. For example, when tired before going to bed, or while eating, I might still watch a video about something I’d like to learn, but rather not scroll through the corresponding docs.
Ideally, videos would be additional to clearly structured and comprehensive text docs. But as much as consumers are people, producers are, too. If they happen to prefer video for whatever reason, and don’t have the resources to do both, video is what you get.
It really depends on what’s being taught imo. If it’s something purely text-based like programming then sure, I absolutely would prefer reading an article to watching a video. For most tutorials though I think there’s benefit in seeing things done visually step by step. Most tools are visual, so learning stuff like 3D modelling or video editing through text can be difficult, but seeing someone do it in front of me makes everything click since I can see exactly what he did and don’t have to read between the steps.
even for visual programs, I absolutely despise the 10min videos for something that I only really care about 5 seconds of. If visual programs had the option of decent text tutorials (with screenshots) it’d be much easier to get into
I prefer written articles
Can’t ctrl+f a video. People don’t often have good presenting skills, talk slowly or with defects. Text is much easier to navigate, faster to read.
I prefer written articles. But for teaching, especially someone who is a junior or novice in the field… Video works better.
So depending on the audience.
Technical documentation of API, Language constructs, and usage (a la mandoc) should always have a standard-compliant (any widely accepted help manual format like mdbook or texi) text form licensed under the GNU Free Documentation License (FDL). This is to ensure that freedom 01 (“The freedom to study how the program works”) is not obstructed in any way.
Videos are tougher due to having a much wider arrange of factors. First off, you’d want to make your videos accessible (using subtitles, on-screen graphics and not just a narration all the way through, translation to other languages). You’d also want to be able to share that video among your peers without obstruction. Just having it be hosted to a proprietary mass-media site like YouTube will not be enough. I have doubts about the “hit record and magic happens” premise, videos are a lot more daunting than text formats if you don’t have the prerequisite equipment and skills beforehand.
If you really want to create videos, you should have a text alternative to the video or at least a technical summary of the video’s topics attached alongside the video so that you can leverage both text and video alongside each other.
I hate videos. I’d rather read a book with 500 pages than watch a video about anything. Actually, I don’t think I’ve ever watched a technical video in my whole life.
If it’s a YouTube video, it probably has been made to monetise, not to share tech material. So I usually avoid YouTube, because most of the time it’s not worth it.
I like written-form documentation, it means I don’t need to play audio in our shared space at work. It’s also a lot faster to find what I’m looking for with written docs than skipping through a video looking for the relevant bits.
Usually when I’m looking for docs, I find that the less time I need to spend in the material, the better. Videos are fixed length and don’t often come with a list of labelled timestamps.
I’m mostly in the pro-written word camp myself, but I have sought out video tutorials in cases where written docs seem to assume something I don’t know. When I’m learning something new, a written doc might have a 3-word throwaway clause like “… add a user and then…”. But I’ve never added a user and don’t know how. If it’s niche open-source software with a small dev team, this may not be covered in the docs either. I’ll go fishing for videos and just seeing that they go to a web-ui or config-file or whatever sets me on the path to figure out the rest myself.
That is to say, video content that shows someone doing a thing successfully often includes unspoken visual information that the author doesn’t necessarily value or even realize is being communicated. But the need to do the thing successfully on-screen involves documenting many small/easy factoids that can easily trip someone inexperienced up for hours.
I’m as annoyed as anyone when I want reference material and find only videos, and I generally prefer written tutorials as well. But sometimes a video tutorial is the thing that gets me oriented enough to understand the written worthy I wasn’t ready to process previously.
Edit: The ubiquity of video material probably has little to do with it’s usefulness though, and everything to do with how easy it is to monetize on YouTube.
I like Fireship style videos for a quick introduction to a subject, but I avoid videos if I quickly need to find something. Text is searchable and just a lot quicker in general.
Technical videos have helped me perfect my pronunciation of “umm” and “uhh.”
Weirdly not many responses are talking about real workspace that much. While written docs are king, video has its own place. Recordings of technical meetings are very valuable and if spoken in english, tools like sharepoint are transcribing them, so you can search them via text. Most often those meetings material will never be written, so video is best second choice.
Demo videos are not “documentation.” They are “demos.”
If you want someone to repeat your steps, it should be code or CLI commands. You can write more descriptive text, but as soon as you reference pictures to show something, you’re introducing ambiguity that text/code can avoid.
UIs change faster than videos and screenshots, as you said, can’t be searched, and are generally less accessible than text.
The source files for documentation should also live side-by-side with the code in the repo. As soon as it goes anywhere else, it immediately goes out of date.
Video demos are nice, but they are not documentation.
Documentation is an ordered list of functions, routines, methodologies, and possibly fields, with a description in a human language (usually English) that follows technical writing standards, assumes nothing about use, and explains what the element is to be used for. It should also contain notes on deprecation, any necessary descriptions of why the program or API is implemented the way it is, descriptions of any expectations of the end user, and no unnecessary frills. They’re technical writing, as a rule.
Videos are for showing you how to get a common job done using the tool or API; they cannot be true docs. It’s great for jumping in, but as docs they would be absolutely unpalatable!