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