Video or Written Documents?

by Heather Laine on May 1, 2014 24 comments

How is it best to deliver help and instruction? I started musing on this question when I got feedback from a customer on just how much he hated video tutorials as a medium to learn programming. Really, I thought? How common is that? His argument was that it’s much faster to read text, pull out the relevant bits and absorb the information you are looking for, and sitting through a video takes longer. I wonder how true this is and in what context. 

Of course, working in support, I’m acutely aware that most people would rather put their hand in a fire than read the instructions. In a perfect world, software would just leap out of the screen, grab you round the throat and yell "Don’t do that to me! Do it this way instead!" Or putting it another way, the interface would be so self explanatory that no-one would need any kind of instructional materials at all. For a complex programming environment like LiveCode, that’s a pretty tall order. You are just going to have to learn the language, sometime, somehow. Read the dictionary, work through some lessons, join one of our summer courses or get some Academy tutorials. But which? Some people prefer to read a book in the bath (our dictionary will probably keep you clean for a year), others might prefer to follow along to a video. The academies are a nice mix, you get both. Every video has a written accompanying document you can copy and paste from. I’d love to be a fly on the wall to see how people actually use them. Do you watch the video? Do you just read the document? How much does the video contribute to your understanding of the document and vice versa? 

I’m the kind of person that likes to learn specific things, when I need them. I am unlikely to sit down and read a book on Dreamweaver from cover to cover, but if I need to know how to do a specific thing like create a rotating gif, I’ll go and look it up. Usually not in the Dreamweaver help, which sucks, but by googling it, and grabbing a nice text tutorial. Yes, I realized in thinking about this, I would not look for a video. Videos annoy me. They mean I have to turn my music off to listen to them, and you can’t copy and paste from a video. I am the Queen of Copy and Paste!

My daughter, on the other hand, will never read anything if there is a video alternative. Reading seems to be something that does not come naturally to the younger generation. 

Relevant to these musings also is the question, is it better to have short self contained tutorials on specific things, or a longer more themed book, tutorial series or video course, going through a subject in depth? Our lessons are an example of the former, they are based around the theory of answering one specific question – how do I use Google Maps in LiveCode? How do I connect to an SQLite database? For me, this is a good way to learn. I’m not overwhelmed by a tome on the theory of storing and accessing data and including it in an app, I just do what I need to do, today. Over time, as I do more and more of these specific tasks, things fall into place and I reach that "aha" moment where it all starts to make sense and I can flexibly create new items from what I have learned and understood. But other people might be happier with a soup to nuts guide before they start on their own first app. 

So where do you guys fit? What comes naturally to a programmer? How and when did you reach your "aha" moment?

This is Lily’s take on this complex issue, after considerable thought:

clip_image002

Heather LaineVideo or Written Documents?

Related Posts

Take a look at these posts

24 comments

Join the conversation
  • Obleo - May 1, 2014 reply

    You need to use both, and even a screen steps model works good also where photos and text is used. There is not a one size fits all customer out there. Companies need to appeal to many different types of customers. That is if they want to appeal to more people and have more overall customers that feel good and have success with the products.

  • Mikey - May 1, 2014 reply

    It depends on the author of the document or the video.

    Generally I’m a jump-in person, but back in The Day, I read all of Danny Goodman’s books on HC from cover-to-cover, because they were really, really good, IMHO, and I found that when I didn’t carefully read them, I missed something very cool or very important.

    Most people seem to make better videos than they make manuals, but manuals with lots of visuals that go out of their way to make things jump out are good. For example, if you want to show me how to use the Save As Standalone Application menu item, you can give me screenshots and tell me to do things, but it’s far better if those screenshots have the relevant controls/fields/etc. circled.

    Too many words, bad.
    Too terse an explanation on a video, bad.

    And one more thing: why do you describe LC as “complex? That’s a problem. If you, and everyone else, for that matter do not view LC as simple, straightforward, and obvious, then you have work to do on the product. BTW, I wouldn’t describe it as complex, but there is definitely work to do to make it more straightforward.

    Heather Laine - May 1, 2014 reply

    I meant complex in comparison to, say, a timer app. Or a recipe app. Something that just does one thing, rather than a programming environment. If I have to read the instructions to use a simple timer, its not a very good timer…

  • Amigatech - May 1, 2014 reply

    For leisurely learning, I prefer to watch a video while following along on my computer. When I am building an app, good searchable documentation works great. The more examples the better! When a computer is not nearby, guides with screenshots are pretty easy to absorb. I like all three, but each has their own appropriate time for best use case.

  • Mark - May 1, 2014 reply

    Programmers are text-based people. They write long scripts and they are able to remember everything from the first to the last character of the programme. They are also able to quickly grasp the structure of a text and will immediately find the relevant parts of that text. That is something you can’t do with a video. That’s why programmers will always prefer text over video.

    Surely, there are quite a few people in the LiveCode community who won’t agree with this, but those people don’t do programming for a living every day of every week.

  • Hermann - May 1, 2014 reply

    It’s good to have videos, because others may like it. I don’t. I’m reading very fast. And I’m learning best if reading (and practise) with scripts others have done, at an steadily increasing level. There are a lot of valuable resources available for this.
    Moreover producing videos has a side effect I like very much. Persons who made a (good) video are immediately ready for writing a good summary or tutorial. Often they do. Thanks.

  • Bill Prothero - May 1, 2014 reply

    I find that I ignore the videos and use the text and screenshot portions. I can cut and paste code, don’t have to stop and start a video, can skip around, return to previous instructions, and it’s all more in the spirit of finding quick and easy information.

  • Paul Dupuis - May 1, 2014 reply

    I worked with a very insightful gentleman many years ago at a US university who, based on research he had done, observed that there are 2 factors in the delivery of technical information to professionals (any sort of technical info to applicable professionals). (1) Just In Time (JIT) delivery – consumers of technical information want to learn the topic X ONLY when it is currently relevant to them. So delivery mechanisms like online documentation, on-demand video, frequently scheduled classes, etc. are important. (2) Multiple Learning Styles (MLS) – different people/personality types learn in different ways. To have the best chance of reaching your whole audience, you must deliver the same content through different mediums – written materials, pod casts, video, classes, etc. – so that it is in the preferred learning style of the individuals you are seeking tor reach.

  • jacque - May 1, 2014 reply

    For me, definitely text. When I need to know something I’m usually in the middle of a project and I need a quick explanation. I don’t have time to watch a video and wait through it to see if it addresses what I need. Another issue is that it is difficult to go back and review what you’ve seen, and I end up taking notes anyway to convert it to text that I can reference later. With text, a browser search can tell me immediately if the page addresses my question and I can leave it open for reference as I work. Videos may be appropriate when the goal is general study without a specific goal, but for reference material they’re my last choice.

  • Sean O'Connor - May 1, 2014 reply

    My preferene is primarily text based documentation idealy with a means to make annotations and marginal notes( if reading an extensive document ).
    Vieeo however is an ideal method of demonstrating a concept in an animated manner as this can sometimes ( but by no means always) clarify things better than text.
    On balance I think it is fair to say that there is no one single panacea for every learning situation.

  • Larry Walker - May 1, 2014 reply

    Heather, good food-for-thought question. I kind of go back and forth, but it seems to depend on what I’m trying to do: is it a general overview of a technique or is it a detailed syntax/usage question?

    On one level, I hate videos: they’re SO SLOW, I can’t skim them, and it’s infuriatingly hard to go back and find something that you remember was in the video but failed to write down. Yet, I really like RunRev Academy videos. They show actual usage techniques, various short-cuts that I’d never discovered before. Text is so prone to containing instructions like “Select ‘foo’ from the ‘bar’ menu” and for the life of me I can’t find out where the ‘bar’ menu is hiding. So I’m stuck dead in the water. But with video, I can go back and single-frame step it until I see what clever little click-combo Kevin used to make something magic happen.

    So given all that, and knowing that different people really DO have different learning styles, I have to end up strongly endorsing your Academy format: let me watch a brief video to get the overview and see a couple of clever short-cuts, then give me a PDF that I can skim and copy & paste from (and PLEASE don’t make the code samples a non-copyable graphic!).

  • Jamie Smith - May 2, 2014 reply

    I’m a web developer by trade and definitely prefer videos for learning. I find I absorb the information much more efficiently. The LiveCode video tutorials are great.

  • Zoltan - May 2, 2014 reply

    For me it is good to start with some good video in order to get the full picture like what the capabilities of the product are, how the video trainer approaches things and so on.
    But, when it comes to do real world stuff, specially when I passed the first steps in the learning phase, then of course, I would prefer some quick written help (preferable contextually, like a key combination on some keyword, or forum/know-how searching … ). The video learning phase could be substituted for a good book though, if video is not available on the subject.
    It also depends on the quality of the material (video or text) of course.

  • Sri - May 2, 2014 reply

    Generally, text-based explanations are best for (abstract) concepts;
    a video example is best for demonstrating a (concrete) technique, especially one involving multiple stages.
    When teaching of an abstract concept is facilitated by the use of a visual-spatial model, then a presentation-type of pictures + text approach would work best.
    A video clip with accompanying written description would mean the best of both worlds.

  • William Moseid - May 5, 2014 reply

    I am Old School. I love to turn the pages and smell the paper. A vidio is good for an overall look-see. But I still love the paper . . .

  • MaxV - May 5, 2014 reply

    Livecode is a total different programming language. All other programming language are just text code. Livecode is a language and an IDE, a total graphical IDE. Users have to push buttons, right clicks, drag and drop.
    So I think that the best is a video as introduction like this one http://www.youtube.com/watch?v=3AbV4Evqy8E&list=UUrP9IskEPHuirOh0KyKjvMA&feature=share&index=17 (the best video about Livecode)
    Then you should use text and many images, a lot of image (screenshots) with red arrows or circles like this one: http://1.bp.blogspot.com/-VTtBuLn2jbg/U2dF-qah85I/AAAAAAAACVc/MrxZehtY7Js/s1600/UserGuide.jpg

  • Lambrechts Fr - May 10, 2014 reply

    LiveCode documentation is very good.
    I prefer videos with a written summary and examples to try, so i can take notes.
    I like Slideshare too http://www.slideshare.net/search/slideshow?searchfrom=header&q=livecode+runrev&ud=any&ft=all&lang=**&sort=

    Note: there is almost nothing in FRENCH about LiveCode,
    and nothing in the FRENCH hardware/software magazines.
    So while learning LiveCode,
    I develop modestly “Une introduction” https://sites.google.com/site/livecodefr001/home

  • James - May 14, 2014 reply

    While I prefer text to video there is certainly a place for videos.
    However most of those that I have watched really need a good edit.
    I do not want to watch a video to see a mouse cursor meander over the screen while the VoiceOver waxes ( and wanes) over some tangential thought or makes multiple approaches to some area only to do something completely different. Most videos are too long, often ( but decreasingly so) to low resolution to actually see required detail and suffer from a poor script ( or non existence of a script.)
    They all need a text accompaniment if they are instructional, always.
    They should all have chapter markers unless they are focused on only a single concept.

  • SparkOut - May 18, 2014 reply

    Content should be delivered in manageable chunks, each addressing a specific task. Each “lesson” should stand alone, have its own objective and be complete.
    The content of other lessons may be groupable together to make a more overall tutorial, in the manner of the Academy.
    The most important thing though, was already said by Paul Dupuis on May 1st. There must be multiple formats for each lesson, but all formats must deliver the same material, just in different ways.

  • BosleyMusic.net - June 26, 2014 reply

    Useful guide you’ve here. I did a write up myself on this subject some time ago, and I wish I had your write-up as a powerful resource back then. Oh well. Thanks again for this content.

    http://www.bosleymusic.net

Leave a Reply Cancel

*