Video Tutorials

[CrazyEddie]

Thanks for the input guys. Still no final decision has been made, so it's all good stuff that helps me to weigh the various options.

CE.

[Salbutamol]

I saw this topic and couldn't resit, as an usability nerd. Video tutorials are a bad idea!

a) Videos cannot be updated (easily), so when there's a change in the API or an errata to fix all that work you put into them is rendered useless.
b) Content inside videos doesn't index in search engines, this lowers the visibility of your website and makes stuff impossible to find by googling.
c) Since the content inside them can't be googled this will result in more people asking questions that are answered in the video already.
d) There's no way of making sure if a video covers a particular element without watching in its entirety.
e) There are a lot of people that can read English but cannot understand spoken English, this happens a lot, more than what you think, probably, since English is actually a very hard language to "hear".
f) Text is superior to video in every sense for documentation purposes. Text can be printed, copied, highlighted, machine-translated. And if it's in the wiki the community can update it.
g) You can ctrl+f to locate a part of it.
h) You can copy a fragment of it and quote it on a forum post to comment, or on IRC, email, your website...
i) Video also can be inconvenient if you happen to be in an office or maybe you are at home and people is sleeping and you dont have headphones...

Consider that the trend of putting everything in video is the answer of publishers to an audience with Attention Deficit Disorder, coders hardly qualify. Ok, we do qualify, but we should manage, because we are are reading your docs because we want to learn how to use something, so there's no need to catch our limited attention span. I guess that you just wanted to present the documentation in a more attractive form. I would recommend you to consider updating your typography and featuring some nice screenshots every once in a while, that would more than suffice.

[kewur]

I saw this topic and couldn't resit, as an usability nerd. Video tutorials are a bad idea!

a) Videos cannot be updated (easily), so when there's a change in the API or an errata to fix all that work you put into them is rendered useless.
b) Content inside videos doesn't index in search engines, this lowers the visibility of your website and makes stuff impossible to find by googling.
c) Since the content inside them can't be googled this will result in more people asking questions that are answered in the video already.
d) There's no way of making sure if a video covers a particular element without watching in its entirety.
e) There are a lot of people that can read English but cannot understand spoken English, this happens a lot, more than what you think, probably, since English is actually a very hard language to "hear".
f) Text is superior to video in every sense for documentation purposes. Text can be printed, copied, highlighted, machine-translated. And if it's in the wiki the community can update it.
g) You can ctrl+f to locate a part of it.
h) You can copy a fragment of it and quote it on a forum post to comment, or on IRC, email, your website...
i) Video also can be inconvenient if you happen to be in an office or maybe you are at home and people is sleeping and you dont have headphones...

Consider that the trend of putting everything in video is the answer of publishers to an audience with Attention Deficit Disorder, coders hardly qualify. Ok, we do qualify, but we should manage, because we are are reading your docs because we want to learn how to use something, so there's no need to catch our limited attention span. I guess that you just wanted to present the documentation in a more attractive form. I would recommend you to consider updating your typography and featuring some nice screenshots every once in a while, that would more than suffice.

well i have to say that your points are true. But..

If the videos have subtitles, the hearing problem would be (sort of) solved.
If the source code will be put as an attachment the ctrl+f problem would be solved.

I understand that when the code is updated, the video would be unupdated. But the videos should not be for the advanced parts of the system. And mostly all the systems core functionality stays the same through out the project. Like the butten event listeners. Or the input system cegui has.

I still think video tutorials are a good introduction to a system and get the attention of the new comers. Since they will learn the basic parts from the video fastest, most of them will be just too sluggish to try a new GUI library. Not many video tutorials are needed to achive this. It still will be a hard work, but a shorter one.


ps. Besides getting people ask in the forums is another way to attract new comers.. Since they would have the same question answered in the forum also..
AND if the subtitles are not embed in the video. Diffrent languages of subtitles could be written. if thats the case i would definetly write my own language's subtitles.

[Salbutamol]

If the videos have subtitles, the hearing problem would be (sort of) solved.

Have you subtitled anything? I've had, it takes around 8 minutes to subtitle 1 minute of video (maybe 4 if we are talking crappy, imprecise subbing). So you are suggesting that 8 times the work is invested on something for no benefit over a text form. Specially, when preparing the video takes more time to start with than writing a text.

If the source code will be put as an attachment the ctrl+f problem would be solved.

No, why the source code? What about the text of the explanations? In fact, 90% of the time I ctrl+f in documentation I look for keywords in explanations, not in source code, because if you knew what function you are looking for you'd look up the api reference, not documentation. That solves nothing. So again, you would need the full transcript. So again, you are saying that all the work is duplicated for no good reason.

I understand that when the code is updated, the video would be unupdated. But the videos should not be for the advanced parts of the system. And mostly all the systems core functionality stays the same through out the project. Like the butten event listeners. Or the input system cegui has.

Your own word: "mostly". It only takes something to be wrong to render a full document obsolete. Nobody leaves wiki pages intentionally obsolete, would you want to do the same with video? I don't think so.

I still think video tutorials are a good introduction to a system and get the attention of the new comers. Since they will learn the basic parts from the video fastest, most of them will be just too sluggish to try a new GUI library. Not many video tutorials are needed to achive this. It still will be a hard work, but a shorter one.

Again, there's *nothing* about a video (if we are talking about programming) that makes you learn something faster magically. Everything that can be shown on a video can be shown on text better.

ps. Besides getting people ask in the forums is another way to attract new comers.. Since they would have the same question answered in the forum also..

Wrong, most of the people doesn't bother to ask in the forum. Check the stats of any forum, you'll see there are 10 times more guests than registered users normally. People usually moves on to another project if they don't find answers immediately. Also, if you get people asking in the forum, it means that the documentation has failed! So by your logic, why don't we delete all the documentation? That way we will "attract more newcomers", won't we?

AND if the subtitles are not embed in the video. Diffrent languages of subtitles could be written. if thats the case i would definetly write my own language's subtitles.

I already addressed this, that is a lot of work that should be used in improving cegui, not subscribing to a pointless fad for no good reason. Also, if you can translate subtitles you can also translate documentation. Which is much easier. Imagine that something in a video is fixed. And this segment that was fixed has a different duration, from 5 to 3 seconds. Now all the subtitles after that part are lagging 2 seconds! You seriously don't know what you are getting into if you go down that route. The videos will quickly get outdated. And be realistic, nobody is gonna sub them or translate the sub, or fix errors in them. Probably, if this is done, what will happen is that you'll end up with a bunch of notes below every video listing the things that are wrong or have changed.

Also, you didn't actually address most of my points.

Of course, if you do both things, if you put everything that's in video in documentation form also, then there's no problem, but do you want to do this, really?

[Jamarr]

I think that you are missing the original intent of the thread:

Anyway the basic idea is that for certain things, it's easier to demonstrate techniques and operations visually than what it is to describe them in text alone. One thing that's already been mentioned was a tutorial on the basics of the CELayoutEditor, we might therefore also assume one for CEImagesetEditor would also be appropriate. So, what other types of tutorial would benefit from having a video element?

As you can see what CE is looking for is potental areas where video can help reduce the learning curve. In the above quote he mentions demonstrating the basics of CEGUI's current visual tools. He's not asking to replace the entire documentation and code-based tutorials with video. They are simply looking for suggestions for video-based information that would help make CEGUI a better product, because some things are better demonstrated with video.

Saying that "nobody" will benefit from video is absurd. And to say that "everything that can be shown on a video can be shown on text better" is entierly untrue. You are being completely selfish and are only speaking for yourself. I will tell you right now that I would have preferred a video-tutorial for the CELayoutEditor and CEImagesetEditor. Have you ever looked over the CEGUI wiki? Have you seen the manual for the CELayoutEditor? It's so bad I don't even want to "search" that document. The wiki is hardly a model for community-driven documentation. Over half the wiki is out-dated, none of the pages have version lables so there is a ton of mis-information, and only a handful of community members has ever contributed too it.

Now no one is dismissing the fact that video's require far more time and effort to maintain than text-based alternatives. This is so obvious it hardly needs to be mentioned. But that doesn't automatically mean video is completely useless. Videos do have several benefits:

1. Introductory videos are appealing to new users
2. People will sit down to watch a 5m video before they sit down to read a 30m blob of text
3. Videos provide multiple sensory inputs, visual/audio, boosting information retention and retrieval
4. Videos help users get up to speed faster than traditional text-based methods
5. Videos are by their very nature promotional tools that far outshine traditional text-based approaches

And that's only handful of reasons, out of many more, why videos can be useful. The point is that video can provide a great introduction to CEGUI and help new users get up to speed quickly, while the wiki and forums remain as the foundation and provide support for the more experienced users.

I think the biggest concern here is not wether videos are useful, because I think they speak for themselves, but that the only developer currently working on CEGUI would be the one investing some of his development time making videos instead of coding/designing.

[kewur]

Have you subtitled anything? I've had, it takes around 8 minutes to subtitle 1 minute of video (maybe 4 if we are talking crappy, imprecise subbing). So you are suggesting that 8 times the work is invested on something for no benefit over a text form. Specially, when preparing the video takes more time to start with than writing a text.

indeed i have. If you are really slow than it would take 8 mins.

No, why the source code? What about the text of the explanations? In fact, 90% of the time I ctrl+f in documentation I look for keywords in explanations, not in source code, because if you knew what function you are looking for you'd look up the api reference, not documentation. That solves nothing. So again, you would need the full transcript. So again, you are saying that all the work is duplicated for no good reason.

,

As I mentioned earlier, video tutorials SUPPORTED with the text document will prove useful.

Your own word: "mostly". It only takes something to be wrong to render a full document obsolete. Nobody leaves wiki pages intentionally obsolete, would you want to do the same with video? I don't think so.

I am talking about tutorials which would embe a CEGUI renderer with Ogre or irrlicht. Or making a new button or smthn. It seems you missed this one entirely.

Again, there's *nothing* about a video (if we are talking about programming) that makes you learn something faster magically. Everything that can be shown on a video can be shown on text better.

Thats just absolutly wrong. When i was first learning OpenGL i watched a few videos and it got me a good head start. Maybe you should stop wasting time trolling on forums and start watching some videos. That may help your attidude.

Wrong, most of the people doesn't bother to ask in the forum. Check the stats of any forum, you'll see there are 10 times more guests than registered users normally. People usually moves on to another project if they don't find answers immediately. Also, if you get people asking in the forum, it means that the documentation has failed! So by your logic, why don't we delete all the documentation? That way we will "attract more newcomers", won't we?

"Most" people are not a concern. This video tutorials would attract new contibuting and ready to learn users. Since new users will ask about a variety of unique issues, it will help the developers to debug, improve and find problems on the system. Since people would be pointing them out

I already addressed this, that is a lot of work that should be used in improving cegui, not subscribing to a pointless fad for no good reason. Also, if you can translate subtitles you can also translate documentation. Which is much easier. Imagine that something in a video is fixed. And this segment that was fixed has a different duration, from 5 to 3 seconds. Now all the subtitles after that part are lagging 2 seconds! You seriously don't know what you are getting into if you go down that route. The videos will quickly get outdated. And be realistic, nobody is gonna sub them or translate the sub, or fix errors in them. Probably, if this is done, what will happen is that you'll end up with a bunch of notes below every video listing the things that are wrong or have changed.

Translating a document and translating a subtitle? thats a hard choice. And im guessing that you are subtitle editing phoebic.

my suggestion for you, if you are going to make people change their minds. use a better language.

[labandunga]

my english bad.
cant understand text.if made videos help really.

[CrazyEddie]

Ok, while it's not an enormous sample size, I think the text + video approach wins the vote. The question as to whether this will go forwards is still undecided - language issues are certainly another point to consider. I might prefer a text / subtitled approach anyway, over narration, not sure - I want things that are easily edited / updated (and easily updated by people who may not be the original creator - narration tracks make that very hard).

It's possible that, when the new skin editor is out, I might try the first such tutorial and gauge things from there as to whether it's something I think we should go with or not.

CE.

[Hideo]

Don't waste your valuable time on video tutorials. Instead, make text documentation first class. Currently it's lacking. Look at all pro libs. They have great TEXT help. Video tutorials are for noobs and will take ages to make.

[CrazyEddie]

Hi,

Thanks for the thoughts. If I can just pick up on one thing You say:

Currently it's lacking.

Which is fair enough, but does not help identify where we can improve. So if you could elaborate a little and tell us in which areas and/or in which ways the documentation is lacking, and some specifics as to how you feel those areas could be improved, that would be much more useful to us. Thanks.

Yes, so called "pro" libs may have first class text help. They also have either paid products, sponsorship, and/or more than two guys working part time

CE.

[Hideo]

The main problem with documentation is that makes many assumptions about the user. You should assume that he knows NOTHING about your lib. You must be verbose. NEVER say something is easy to do. For you it is easy, since you work on this for years. For a guy who just takes his first steps everything is new and difficult. You should explicitly write in every tutorial what headers to what libs to include. You did a large job with features of this lib. Documentation is equally important.

[CrazyEddie]

The point about making too many assumptions is fair comment. While I don't believe in taking the 'hand holding' too far - since this is not intended as a library for beginners - there are examples (such as the headers one you cite) where we miss out information that could have been provided.

You did a large job with features of this lib. Documentation is equally important.

This is true. Though I am just one man. I'll take the opportunity to remind all those who read this that we do - and have always - accepted patches to the files in the repository and obviously the Wiki'd documentation can be updated by anyone. So I'm not going to shoulder all the responsibility of this perceived deficiency; since this is supposed to be an open, free and community orientated project - the community can shoulder some of the responsibility for the state of things also. So, step up guys!

CE.

[Luiji]

I think Video Tutorials would be very useful. Text tutorials are good for many things, such as explaining compilation, but when it comes to stuff like the CELayoutEditor it is much more useful to have a visual of what's happening. This also prevents users from misinterpreting the instructions.

[CrazyEddie]

Hi,

Yeah exactly. This is the kind of thing I had in mind when I first suggested this idea - to demonstrate those things that are by their very nature 'visual' and hard to describe otherwise. I'd never really intended to make videos of CrazyEddie typing a lot of code

Once the CESkinEditor is done, I'll likely make a couple of videos to demonstrate the basics of that new tool - and depending on the response to those will decide whether it's something I wish to continue with or not

CE.

[Mikademus]

Part of the entrenchedness evident in this thread comes from that what we're dealing with here is a very bipolar topic: making a GUI is as much about programming as it is about visuals. In a sweeping generalisation we can assume two user types and usage foci, coders and designers, which would tend to prefer documentation/code samples and visual presentations, respectively. Neither is wrong, and this is worth bearing in mind.

So for you that argue strongly against visual tutorials, your points are certainly relevant, and I'd also ask you to accept that a large part of the user group of CEGUI would benefit from visual aids. And vice versa, those of you arguing strongly for video tutorials on the expense of documentation, please remember that coding is as an important aspect.

Ideally, both will go hand in hand and complement each other.