Join the FREE events running through Feb & March. Community Outreach in NYC >

Video or Written Documents?

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:




  1. David Murphy

    Different people learn best in different ways. Most of us also prefer one method for some things and another for others. I find videos useful sometimes, especially explaining visual things. But sometimes I watch videos form Infoq on tech topics and am screaming abuse at them within minutes, while they umm and aaah etc. Often one hour of video can be as informative as 10 minutes of text.

    Also, even if I like a video, a text version which I can easily refer to and copy / paste when needed.

    To learn a new technology often you need a longer general piece to get an overview. BUt then you need bite sized pieces for specific tasks.

    Obleo got it bang to rights


    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.

  3. SparkOut

    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.

  4. James

    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.

  5. Lambrechts Fr

    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**&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”

  6. MaxV

    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 (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:

  7. William Moseid

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

  8. Sri

    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.

  9. Zoltan

    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.

  10. Jamie Smith

    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.

  11. Larry Walker

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

  12. Sean O'Connor

    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.

  13. jacque

    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.

  14. Paul Dupuis

    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.

  15. Bill Prothero

    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.

  16. Hermann

    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.

  17. Mark

    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.

  18. Amigatech

    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.

  19. Mikey

    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.

    1. Heather Laine Post author

      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…

  20. Obleo

    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.