The Seven Voyages Of SteveMar 3, 2023

Finally started watching a (long!) video about the UE Gameplay Ability System. I'd tried to get a sense for it from the written docs, but they just don't go into enough detail on how & why you might use it in practice. More like 1 paragraph on each bit & then "go read the Lyra source". Needing to watch a *3h* video has been a blocker on me bothering to dig more before now.

I don't think it's something I'll use on this game, but I can definitely see the utility. Just a lot of moving parts!

Phillip CarterMar 5, 2023
Show threadThe Seven Voyages Of Steve
Tech industry, please hire more writers. I can happily read docs for 3h and get much more out of them than watching a video for 3h. And while I'm watching the video, I'm making copious notes so that I don't have to watch the video *again* later to refresh my memory. If it was written down in the first place with good indexing I wouldn't have to do that. Video is such a crap way to document things.
Mar 3, 2023 at 3:22pmWeb
Show threadThe Seven Voyages Of SteveMar 3, 2023
I know that the excuse for this is “young people like video”, but I call BS on that. I think the *real* reason is that with video you can repurpose your existing dev talent and not have to hire tech writers. Just put the most cogent of your devs in front of the camera for an afternoon, job done right? Shared skill set, no need for writing specialism or ongoing editing / maintenance, just stick the video online and point to that for the next 3 years. Absolutely says cost cutting to me
Show threadThe Seven Voyages Of SteveMar 3, 2023
Also I want to point out that with any talk over 30 minutes your stupid self-sabotaging human brain is going to eventually isolate the one very slightly annoying involuntary thing the speaker does and *fixate on it* until you can hardly bear to listen to them anymore. Not the speaker's fault, we all have these things, that's why we don't *normally* shut ourselves in a soundproof room for 3h with one other person talking at us non-stop.
Show threadGiles GoatMar 3, 2023
@sinbad
Hey that's NOT how I remember certain lessons at UNI with the teacher also writing on the whiteboards formulae non-stop 😂 I still can't forget "that afternoon" when ".. the general starred polygon formed by connecting N points in a plane .. " ( after 2 hours non stop and still going ) ... then I asked myself WTF AM I DOING HERE !!!?? .. A critical point, that was the beginning of my decision to QUIT UNI, which in the end I did .. I still have nightmares ... ".. for certain epsilon ".
Show threadGiles GoatMar 3, 2023
@sinbad
I must add that "the way I remember UNI in 1994" ( in Italy ) was NOT "we are here to tech you things" was ALL about "we are here to keep the best and throw away all the rest" .. it was .. brutal to say the least .. "If you did not understand a thing it was all YOUR fault" and if you could not keep up with speed you were GONE . I never struggled so much (*) to understand things and finding "all by my own" .. It wasn't exactly "learning" it was a "trying to learn the super hard way".
Show threadGiles GoatMar 3, 2023
@sinbad
(*) no I am wrong .. I think I should add here trying to develop native CPP on Oculus using ANDROID STUDIO following the setup instructions that NEVER WENT AS THEY SAY IT SHOULD getting NUTS with that "Gradle" and makefiles in the end having something that did work for 2 weeks until it started to "partially fail" ( Android Studio NOT the code ) generating mysterious errors and not doing things it should have been done but never worked ! I think that was really "close to madness".
Show threadThe Seven Voyages Of SteveMar 3, 2023
@gilesgoat hey at least you lasted until Uni, I bailed during A-Levels 😛. I liked the subjects, just not the schooling experience
Show threadJames CarrMar 3, 2023
@sinbad THIS. As soon as I notice the "um" punctuation, or the lip smacking, or (take your pick), I'm done.
Show threadSocar MylesMar 3, 2023
@sinbad What I REALLY hate is when I need the answer to a very simple question, like "how do I attach the strap to my new camera?", but ALL the answers are in video format, and ALL those videos are stretched out l-o-n-g so they can have more ad breaks on YouTube. I don't need to watch ten minutes of blather for a two-sentence answer.
Show threadZachary Powell 🥑Mar 4, 2023
@sinbad as someone that's very dyslexic if I'm trying to understand something new, videos are infinity better for me and much more accessible then a wordy blogpost. BUT it needs to be written down as well, particularly for documentation so I can reference later. In short do both!
Show threadeyrea 🇨🇦Apr 7, 2023

@devwithzachary @sinbad Multimodal is the way to go. People tend to discuss graphical dyslexia more, but auditory dyslexia is a thing too. I've never been diagnosed, but instructional video without being able to take notes is an absolute agony for me. I'd much rather read some docs.

The point is to reach everyone, and for that thorough, multimodal documentation is required. And that requires it to be seen as part of the product, not an add-on.

Show threadGerd FlaigApr 7, 2023
@sinbad Or, even better, combine written text and video where it makes sense. A ten second video of a particular user interaction, embedded in the documentation text, can sometimes help tremendously.

Of course, that's even more expensive than just text or just video but may still be worthwhile if the consumer to producer ratio is high and folks would otherwise generate high support cost.
Show threadDamien GuardMar 3, 2023
@sinbad That and the fact I want the video to skip skip skip skip no, this is the bit I need slow down slow down.
Show threadMartin KiftMar 3, 2023
@sinbad unless videos are correctly chaptered up, which from my experience epics rarely are, then not only are they terrible to “browse” for information but they are terrible to maintain as well.. hence the number of out of date videos on YouTube on most unreal topics, esp from epic themselves.
Show threadThe Seven Voyages Of SteveMar 3, 2023
@MouseByTheSea this one is chaptered which I guess makes it better than the average, but still. I honestly think that there being a tacit acceptance that video is usually out of date in some way is a "feature" for publishers, vastly reduces the ongoing effort required versus maintaining good documentation
Show threadMartin KiftMar 3, 2023
@sinbad thinking on, a chaptered video would in theory allow one to re-record chapters to keep the video up to date - in reality, I don’t recall ever seeing this done.
Show threadMatt MascarenhasMar 3, 2023
@MouseByTheSea @sinbad Oh, I like this idea, and can pretty readily imagine how to do it (as someone who both indexes videos, and fancies a world in which our messages in whatever medium are generally editable and may be referenced by version).
Show threadカルちゃんMar 4, 2023

@sinbad I have rather well educated young adults at home. The kind who actually read books. Amazing eh? Wait. You have no idea how hard it is to get them to read information/documentation rather than watching it. They just won't. I keep telling them they can get the same amount of information from a 1-hour video by reading doc for 2-3 minutes (I don't feel like I'm exaggerating here). When I prove it to them they agree, then they go right back to watching videos.

As for myself, I absolutely refuse to watch documentation or information in video form, no exception. Life is too short, especially toward the end.

Show threadGerbrand van DieyenMar 5, 2023
@calchan @sinbad I got that impression too. Most students and young people in IT don't read. No books. Just video. How can we change that?
Show threadlachezarMar 5, 2023
@sinbad it is not just “young people like it”, but also people with learning disabilities have it easier to absorb information from video.
But in general, I agree that if you want easy way to access the information again, it needs to be indexed and in text format.
Show threadBen EvansMar 5, 2023

@sinbad To give you a single data point that somewhat contradicts your thesis - for a long time I resisted doing much video, despite gentle encouragement from my publisher.

When I actually sat and looked at my revenues, a substantial chunk of them came from video - quite a lot more than I expected. So, *someone* is buying videos - and this is for content where at least a chunk of it overlaps with what's available in book form.

Show threadChristiaan MolemanMar 5, 2023
@sinbad A lot of things are better explained visually. Docs are great for reference and looking up specific details. Videos are better in other cases where you could write pages trying to describe a concept or action, or you could just SHOW it. Not everything should be video but not everything should be a document either.
Show threadhighly principled invertebrateApr 6, 2023

@sinbad "Young people"??? If you've got sensory processing problems, are deaf or are not good at learning via watching demonstrations only, then it doesn't matter your age, you won't want the video only & need written instructions. I'm 2 of the above and at not yet 40 really shouldn't be considered "old" either.

I also think it's a rather comical situation that's been built overall with this mess, as it's simultaneously claimed that computers are universally accessible tools, that not enough disabled are using computers and that training methods can be reduced in diversity, especially new technology, because everyone likes things as they are.🙊🙈🙉

#Tech #Accessibility #TechWriting #Technology

Show threadTine SchenckMar 3, 2023
@sinbad YES!!! I hate using video for information that I need to look over again and again.
Show threadigrir - Wishlist AfterLove:EPMar 3, 2023
@sinbad
this is so very much true. For so many time I just need some skimming to digest the idea of a concept without have to watching the entire information. And the best part is, writing docs are easily searchable!
Show threadDaniel GibsonMar 3, 2023

@sinbad
> And while I'm watching the video, I'm making copious notes so that I don't have to watch the video *again*

yep.. and that often requires pausing the video to take a note, which means that watching it takes *even longer*

Show threadAndre WeissflogMar 3, 2023
@sinbad Amen! About the only scenario where I started to prefer short per-topic-videos is for learning visual tools like Blender.
Show threadJimBobBennettMar 3, 2023

@sinbad Different folks learn in different ways. Video is so important when you need to show, or for the younger generation who learns from videos. Docs are the ultimate details for those who learn from reading, and to provide the 'golden source' information. Docs are easier to update than video so go out of date less often.

Good content starts with good docs!

Show threadThe Seven Voyages Of SteveMar 3, 2023
@JimBobBennett I agree, my problem is when companies treat video as the primary and the "golden source" has huge gaps
Show threadJimBobBennettMar 3, 2023

@sinbad so much this!

Written docs as the golden source.

Video should only be the golden source if you have to show something, such as with hardware short videos can be better than text.

Otherwise start with detailed docs, user guides, quick starts etc. Video is great, but is phase 2 - and should be split into short form to answer questions, as in this video shows you X and only X, with longer form tutorials. I have so many opinions in this space...

Show threadFrancesco Giordano 👾Mar 3, 2023
@sinbad I honestly can't stand videos... gimme written docs any day!
Show thread💡𝚂𝗆𝖺𝗋𝗍𝗆𝖺𝗇 𝙰𝗉𝗉𝗌📱Mar 3, 2023
@sinbad
Video is good for the holes in the doco, cos they can't skip things. You can SEE what they're clicking on, and "Ah, THAT'S what they failed to mention in the doco!". If they wrote it better in the first place then you wouldn't need video, but almost literally nobody does (i.e. doesn't cover all cases, doesn't have step-by-step, doesn't link to assumed knowledge, etc.).
Show threadSte PickfordMar 3, 2023
@sinbad hell yes.
Show threadJack AponteMar 3, 2023
@sinbad As a tech trainer I'm hearing very often from end users that they will *not* make the time to watch a pre-recorded training video or webinar. They either want clear written documentation or another live training, even if it's presenting the same material as the recording. It just *works* differently.
Show threadChuck MunsonApr 6, 2023
@jackaponte @sinbad Sounds like you are talking about at least two different needs. I've come to love training videos and webinars for learning new stuff, especially in depth. But when I'm trying to figure something out, I want text documentation or a Reddit, Stack Overflow, or social media thread. I really get annoyed when I run into videos about the problem. I don't want to waste time with videos that don't get to the point and videos mean I have to turn off streams or videos I'm watching.
Show threadKeith SoltysMar 3, 2023
@sinbad
As a retired technical writer, I heartily endorse this message.
Show threadWanderingBeekeeperMar 3, 2023
@sinbad I'm a former tech writer working as a Major Incident Manager because there's no career path for tech writers. They're the last to be hired, and the first to be cut. They're the lowest paid on the team, and three quarters of the developers regard them as a nuisance at best, a hostile intrusion at worst. If someone wanted to pay me the same amount I'm currently making as a MIM to write doc, I would write doc. I blame capitalism and techbro obsession with interactivity.
Show thread`Da ElfMar 4, 2023

@WanderingBeekeeper @sinbad Ah yeas, and that's a truth. I took three years of Tech Writing in College and University.

I use those skills nearly every day, but it's never been my actual Job.

I'm so happy when my employer has an actual Tech Writer on staff. They're usually not busy ... until I find out about them. Then THE FUN begins and we attach at the shoulder and I guide and they write and we Document!

Last Hired and First Cut is the truth. That's how I lost my last two writers. :(

Show threadeyrea 🇨🇦Apr 7, 2023
@WanderingBeekeeper @sinbad Which is hilarious, because (as I'm sure you already know) watching video is far more passive than the act of reading.
Show threadRichard StocksMar 3, 2023
@sinbad Not just tech. Drives me nuts when I have to scroll through pages of search results to find a document (on almost any subject) instead of a YouTube link. I don’t want to watch a video, I want to study the text.
Show threadDavid ZaslavskyMar 3, 2023
@sinbad Agreed! I hate trying to collect information from videos.
Show threadNire BryceMar 4, 2023
@sinbad this doesn't help solve the actual problem, but as a workaround: in the 3 dot menu where share/loop/download/etc live, there's an option for 'show transcript' in most videos, and you can ctrl-F the (very imperfect) speech-to-text often enough to narrow things down ime
Show thread`Da ElfMar 4, 2023

@sinbad So much this. I read at an alarming rate, but video is linear and I have to work at the speakers pace.

I've never read, "Um..." 52 times in a Technical Document, but I *have* heard it in a 30m video (yes, I went back and counted I was so irritated).

Editing:
Document - Trivial
Video - ROFL, not.

"Young People prefer video" is bullshit. TokTok for 30seconds while waiting in line at Starbucks absolutely, but Technical stuff? Refined, distilled, unadulterated, Bullshit.

Show threadmelanie ensign (she/her)Mar 4, 2023
@sinbad we’ve got technical writers at @Discernible for anything security or privacy related, & a network of freelance technical writers for other topics.
Show threadMichael GemarMar 4, 2023
@sinbad Don't worry, I'm sure we'll be getting ChatGPT-written docs very shortly...
Show threadInsubordinantMar 4, 2023
@sinbad This is so important. I'm constantly annoyed by video how-tos. I don't want to sit through 20 minutes of your story about your cat before we get to the thing you're instructing. Please, use text!!!
Show threadArgot_RobbieMar 4, 2023
@sinbad @sladner People volunteer to listen to podcasts - "Ah, uhh, y'know, uhh ... " - so there is solid evidence most people hate themselves, have no respect for their time, or simply cannot read.
Show threadbirdpoofMar 4, 2023
@sinbad Oh god, this. I take so many notes of live trainings and video trainings. They're too goddamn linear and you can't search for the practical bits. Waste of time!
Show threadThe_Turtle_MovesMar 4, 2023
@sinbad some years ago, I bought a wheelbarrow. The only assembly instructions were a link to a YouTube video. Trying to watch a YouTube video on a phone screen in bright sunlight, and every time I paused it to try and find the right screw, the screen turned off and I'd have to watch ads again...
Show threadThe_Turtle_MovesMar 4, 2023

@sinbad Figuring out what bolt size I needed for a step meant skipping back to the beginning to rewatch the 'parts list' piece to find out what 'bolt C' was supposed to be, and then needing to try and find where I was before. Yeah, they had made a video of a written manual. Even a PDF would have been better.

Of course, why a wheelbarrow needs 18 steps and 6 different sizes of bolt is a whole other problem.

Show threadJohn ClearyMar 4, 2023
@sinbad @brentsimmons I think both are valuable actually. We use screen-casts for basic “how to” content for our users, and Notion written (w/ screenshots where needed) for reference documentation for complex tasks. I think end-users do prefer Video for a lot of basic things. But whenever there are code snippets etc. a well written Notion page is way better.
Show threadKevin Karhan Mar 4, 2023

@sinbad +9001%

written documentation is easily searchable, accessible and translateable.

Videos only work for simple hands-on / show & tell kind of content and not as replacement fir proper documentation!

Show threadPēteris KrišjānisMar 4, 2023
@sinbad videos are no go as general documentation. Videos are good of giving kickstart way to open and start project, so people aren't getting stopped at simple things.
Show threadGreg StolzeMar 4, 2023
@sinbad
Shhh! In the current climate "hire more writers" will inevitably be heard as "use ChatGPT!"
Show threadSelf-hosted Idiran (AKA El Lamboz) 🚜 🐧 🎹 Mar 4, 2023
@GregStolze @sinbad As a game background writer, ChatGPT plainly sucks. I had it try to describe terran expansion 200 years after jump drive had been developed, told it to be creative and ignore all stereotypes and the most creative thing it spat out was "the culture x and y is inclusive".
Show threadGreg StolzeMar 4, 2023
@idiran @sinbad Spicy Autocorrect scores again!
Show threadRobJLowMar 4, 2023
@sinbad Not just tech industry, either. I don't like spending half an hour listening to somebody slowly saying something I can read in five minutes.
Show threadMike McBrideMar 4, 2023
@sinbad I've used video to supplement written training materials because it is very useful to "show" how something is done. But, it has to be specific to one process. If it takes more than 15 minutes to show, the video isn't helping.
Show threadIsaac RabinovitchMar 4, 2023
@sinbad It isn't just the industry. The web is full how-to videos that take an hour to answer a question that a doc could answer in a few minutes of reading. But it takes a lot more mental effort to write a good doc (I used to do it for a living) than to babble at a camera.
Show threadDenis VeltsonMar 4, 2023
@sinbad amen :)