Why do online tutorials confuse you?

A place to discuss the implementation and style of computer programs.

Moderators: phlip, Moderators General, Prelates

User avatar
Steax
SecondTalon's Goon Squad
Posts: 3038
Joined: Sat Jan 12, 2008 12:18 pm UTC

Why do online tutorials confuse you?

Postby Steax » Mon Dec 05, 2011 5:55 am UTC

For my new collaborative blog, I'm going to be writing a large series of tutorials that cover the main aspects of web development, along with design. This means lots of chapters, getting people up and running with their first HTML tags to showing people how to design a database to user interface to accessibility to tools and to avoiding CSRF attacks.

I'd love some feedback from all of you: in general, when reading online tutorials for code, does anything annoy you most? Did any particular ones stand out for a reason?

I know a lot of tutorials confused me because of:
- Expecting too much prior knowledge without warning ("so, open up your text editor and write a generic HTML page, then, in the body, type..." in a tutorial for basic HTML)
- Not being clear on the scope (e.g. "will this tutorial on deploying wordpress on amazon EC2 explain the basics of cloud computing?")
- Too much technical talk ("Take the second p tag and remove the name attribute...")
- No easy way to copy-paste code from the tutorial
- Too dependent on tutorial example files (if possible, I prefer them to be copy-paste-able)
- Too few instructions and too much code
- Ambiguous text/unfinished statements ("Clearly, this introduces a security problem, but it's okay for now")
In Minecraft, I use the username Rirez.

gorcee
Posts: 1501
Joined: Sun Jul 13, 2008 3:14 am UTC

Re: Why do online tutorials confuse you?

Postby gorcee » Mon Dec 05, 2011 8:24 pm UTC

Tutorials I've encountered often suffer one major problem, which manifests itself in a few different ways: lack of respect of the learning curve.

In one regard, this can come up as an over-emphasis on simple aspects of the lesson. If you're writing a tutorial for how to implement the factory pattern in object-oriented programming, for instance, don't waste time explaining what a double is. It's fair to assume that if the person is seeking out this tutorial, they're already aware of basic programming jargon and techniques.

In another regard, this problem arises as a mistaken assumption that by presenting a few basic things first, the reader now understands the background material well enough that you can jump into an advanced example. For the factory pattern example, it would be like 1.) introducing primitive types, 2.) introducing classes, 3.) HUGE LEAP FORWARD IN LOGIC, 4.) introducing how to apply a factory pattern to an application that involves access to a database or web front end or somesuch. In other words, the reader goes, "yeah got that. Ok, got that, too. Wait, where the fuck do you get off doing this? How about a simple example first?"

I've recently come across this in trying to really understand Data Binding in WPF. A few tutorials I've come across basically go like this:

1.) Alright, WPF uses XAML! XAML is like XML but with pre-defined elements that dictate your user layout. Some of these elements are containers, like <Border />.
2.) You can do some cool things using XAML attributes. Watch how I round the corners in this Border!
3.) Alright, now that we've gotten that out of the way, let's talk about two-way databinding in the border. Of course, you'll want to be sure your class implements INotifyPropertyChanged. And then you'll need to specify an ObjectDataProvider like this....

It's like woah. Hold the fuck up. What does this syntax mean? Why do I need to structure my XAML this way? How do I structure my code-behind to reflect data binding? Is it best practice to write classes specific to the data binding? Is it better to manage the data binding in the XAML or the code behind? And what happens if I have two instances of a class, how does it know what to bind to?

A good tutorial, on the other hand, respects the assumed level of knowledge of the programmer, and then maintains that reference all the way through. If you assume that they're a novice, then write each step of the tutorial to that entry reference point, not some interim point. If you assume they've got some experience, write to that level all the way through.

In the example I gave here, the tutorial starts by assuming the reader is a blithering moron when it comes to XML ("Wow, did you know you can change the way things behave by manipulating 'attributes'?! Isn't this fancy?!"), and then transitions to assume they're experienced .NET programmers that frequently run around implementing INotifyPropertyChanged like it's as simple as wiping their ass. Either they're new, and then step 3 makes no fucking sense, or they're not, in which case steps 1 and 2 are pointless, because you can assume they've encountered XML before (and if they haven't, just link them to a different tutorial).

User avatar
Steax
SecondTalon's Goon Squad
Posts: 3038
Joined: Sat Jan 12, 2008 12:18 pm UTC

Re: Why do online tutorials confuse you?

Postby Steax » Tue Dec 06, 2011 5:12 am UTC

I've noticed that problem a lot too. My solution to that would just be to make more tutorials, and cross-link them into a "prerequisite" tree of some sort, where one tutorial assumes understanding of a set of other tutorials. That, and probably a lot of cheat sheets and terminology explanation. Nothing is more annoying than being told to do something in geek-speak.

Associated with that problem is the issue of being unspecific - for example, "Integrating Amazon S3 with Wordpress". Someone with no prior knowledge of Amazon's services may assume that the article is about getting Wordpress to run on the cloud. It makes no sense to people who are used to, say, shared hosting, especially since they just call Amazon S3 a "cloud-based data-storage infrastructure accessed through an API". It turns out the point of the article is about backing up Wordpress content, via a plugin, to a S3 server. Conclusion: Don't use vague titles, be as specific as possible.
In Minecraft, I use the username Rirez.

User avatar
darkspork
Posts: 532
Joined: Tue Sep 23, 2008 12:43 am UTC
Location: Land of Trains and Suburbs

Re: Why do online tutorials confuse you?

Postby darkspork » Wed Dec 07, 2011 8:07 am UTC

If anything, I'd break the tutorial up into explicit "chapters" with a clear goal. At the beginning of the chapter, provide an example that should make sense to the reader on successful completion of the chapter. If it already makes perfect sense, provide a link to skip the chapter. What I hate is when a tutorial brings up a chapter on... let's say... "Writing simple SQL queries", I skip it because "I already know this crap", only to find later on that the tutorial's idea of a "simple SQL query" includes copious levels of nested INNER JOINs that the next chapter rolls right through. In another approach, you could try to make the tutorial under the assumption that a person will jump in at whatever chapter they feel like they belong in. Provide links back to where you explained things up to a few chapters before (For example, "Overriding Operators in C++" might want to link back when it mentions defining a function or using pointers, but probably not all the way back to "Compiling C++ Programs")

To me, that feels like the best way to put the tutorials in perspective and make them available to students of all tiers.
Shameless Website Promotion: Gamma Energy
My new esoteric programming language: GLOBOL
An experiment to mess with Google Search results: HARDCORE PORNOGRAPHY HARDCORE PORNOGRAPHY

Anonymously Famous
Posts: 242
Joined: Thu Nov 18, 2010 4:01 am UTC

Re: Why do online tutorials confuse you?

Postby Anonymously Famous » Wed Dec 07, 2011 7:25 pm UTC

I'm popping on here simply to say that you seem to have hit all of my pet peeves, and that I want a link once you're done.

User avatar
Steax
SecondTalon's Goon Squad
Posts: 3038
Joined: Sat Jan 12, 2008 12:18 pm UTC

Re: Why do online tutorials confuse you?

Postby Steax » Fri Dec 09, 2011 1:30 am UTC

Thanks dorkspork, I'll make sure to include comprehensive "session goals" and scope explanations. I know that pain - it's annoying to jump over something, thinking it's straightforward, then later to get confused and doubling back.

Anonymously Famous wrote:I'm popping on here simply to say that you seem to have hit all of my pet peeves, and that I want a link once you're done.


Sorry, I'm writing them in Indonesian. I can probably point you in the direction of a good tutorial, though, if you're in the web development/design business.
In Minecraft, I use the username Rirez.

User avatar
You, sir, name?
Posts: 6983
Joined: Sun Apr 22, 2007 10:07 am UTC
Location: Chako Paul City
Contact:

Re: Why do online tutorials confuse you?

Postby You, sir, name? » Fri Dec 09, 2011 5:31 pm UTC

My main criticism of tutorials is that they're often short, and contradictory to other tutorials. Hence, I prefer books that cover a wide topic consistently. Books are also generally written by people who know what they're doing, whereas tutorials can be written by any 15 year old with decent technical English, without a clue about best practices and what's standard.

I think learning stuff by tutorial is a pathological programming culture. It breeds cargo cult programmers. A decent programmer needs to understand the language (from books), the theory (from books and/or classes), and the library (from documentation and API references). There really isn't much need for tutorials in this.

So my advice is to make it as book-like as possible.
I edit my posts a lot and sometimes the words wrong order words appear in sentences get messed up.

User avatar
Steax
SecondTalon's Goon Squad
Posts: 3038
Joined: Sat Jan 12, 2008 12:18 pm UTC

Re: Why do online tutorials confuse you?

Postby Steax » Sun Dec 11, 2011 8:51 am UTC

Thanks YSN! My goal here is to make a set of online tutorials centered around a larger library of topics, so it is indeed more like a book than separate tutorials floating around. I'm doing this because there are a lot of dodgy and cheap books that claim to teach things, but are really just ripoffs of online tutorials or just code to copy-paste. Many a programmer don't have the chance to buy expensive books in my country, so I'm trying to compensate.

I'll make sure to separate the language and the theory, as you mentioned. That's really useful, on second thought.
In Minecraft, I use the username Rirez.

User avatar
Zamfir
I built a novelty castle, the irony was lost on some.
Posts: 7594
Joined: Wed Aug 27, 2008 2:43 pm UTC
Location: Nederland

Re: Why do online tutorials confuse you?

Postby Zamfir » Mon Dec 12, 2011 9:10 am UTC

Make sure to get input (not just a quick look) from people who do very different stuff than you. My personal peeve with tutorials is that they usaully make unstated assumptions about what you want to do with them, and in what circumstances. And they often work with toy-problems, so it's often far from clear what kind of environment they had in mind when setting up the tutorial.

So you get advice that is perhaps indeed good practice when you are in a team of 3, setting up a web front for a shop on a one-off project basis. But not for a a hobbyist making something at home, or a consultant combining internal databases in a company, or a member of a large development group making boxed desktop software, or a scientist doing data manipulation to be used by colleagues who have access to the source code, etc. Or more subtly, the tutorial assumes that data has a certain typical complexity, that information typically flows mostly from this side of the program to that side, that no one wants to modify these parts often, but everybody needs high flexibility in those parts.

I guess that's unavoidable if you're writing from personal experience, but it can be highly frustrating. It might be related to YSN's mention of cargo-cult programming: if you are learning something, you have to assume the teacher knows better than you in some respects. But if you are not really interacting with a teacher, just reading a tutorial, you easily end learning things that aren't suited to your situation, and you only find out much later.

Having input from very different people than you might help to warn you against that. Also, be very clear for what kind of cases you are intending the techniques you are describing. Even when you are describing a toy example, explain how a typical real case would be like, in what situations you personally find this useful. Help people to get early warning whether they are in the target group.

User avatar
Mat
Posts: 414
Joined: Fri Apr 21, 2006 8:19 pm UTC

Re: Why do online tutorials confuse you?

Postby Mat » Mon Dec 12, 2011 11:25 am UTC

You seem to be on the right track, and have covered most of the common pitfalls.

Too few instructions and too much code
This one can go the other way as well (hello unix man pages :x ). Examples are a great way of conveying info quickly, as long as they are relevant to the text and not some esoteric thing you created just to show off. I prefer it when they're used as as an illustrative tool, rather than the "recreate something the author wrote earlier a piece at a time" style approach some tutorials take, where the entire tutorial is basically focused around a single example.

http://www.diveintopython.net/ is heavily example based, but covers everything the target audience (people with experience in other languages) need to know to get started with python. What sets it apart from most other tutorials is partly the length and broad scope, but also the way it annotates each example and compares things to stuff the reader may be familiar with.

http://diveintohtml5.info/ - also by the same author - is great too. Basically you should just copy everything this guy does :)

Also, the number one thing that drives me away from tutorials is poor formatting and layout. Tiny unreadable text, lack of syntax highlighting, related content broken up over 10 short pages, etc. Please don't do this.

User avatar
Steax
SecondTalon's Goon Squad
Posts: 3038
Joined: Sat Jan 12, 2008 12:18 pm UTC

Re: Why do online tutorials confuse you?

Postby Steax » Mon Dec 12, 2011 1:55 pm UTC

Zamfir wrote:And they often work with toy-problems, so it's often far from clear what kind of environment they had in mind when setting up the tutorial.

But if you are not really interacting with a teacher, just reading a tutorial, you easily end learning things that aren't suited to your situation, and you only find out much later.

Having input from very different people than you might help to warn you against that. Also, be very clear for what kind of cases you are intending the techniques you are describing. Even when you are describing a toy example, explain how a typical real case would be like, in what situations you personally find this useful. Help people to get early warning whether they are in the target group.


I think I'm specifically avoiding toy problems - I find them extremely annoying. Saying "well, let's try splitting that array in half" is useful but is more "hey, memorize this" than "hey, if you need to break a list into 2 columns, this is what you do".

I'm definitely going to have a set of beta readers (actually, my closer friends who want to learn this stuff, so they're the perfect target audience too). I think, though, I'll stick closer to them and maybe even do some good old over-the-shoulder testing as they try out tutorials. Thanks!

Mat wrote:Examples are a great way of conveying info quickly, as long as they are relevant to the text and not some esoteric thing you created just to show off. I prefer it when they're used as as an illustrative tool, rather than the "recreate something the author wrote earlier a piece at a time" style approach some tutorials take, where the entire tutorial is basically focused around a single example.

Also, the number one thing that drives me away from tutorials is poor formatting and layout. Tiny unreadable text, lack of syntax highlighting, related content broken up over 10 short pages, etc. Please don't do this.


A sub-problem I identified today was the lack of specificity when writing code; many a tutorial just say "change X to Y" without saying which instance of X, which file, etc - and it's especially confusing when they just say "now, add this code". I think what I'll do is supply the full file of code for each code block, but collapse it to just the specific bits (maybe show the lines immediately before and after, and fade them out slightly). An option to expand the full file will be available for those who want to jump straight into a section, without having to re-read from the beginning.

Definitely not breaking it up into short pages, either. I'm just having them as single pages, with links to each section available at all times.

I'm totally going to use the annotation method used in diveintopython.net. I think it's also a great way to convey minor bits of details (such as "why did you bind to keypress instead of keydown?") without distracting from the main flow of the tutorial.

Dive into HTML 5 was actually my original inspiration. It taught me a ridiculous amount of what I know about HTML 5. Wait... maybe everything I know. Yeah. I'm also using the style of large, clear copy, and minimizing on distractions.
In Minecraft, I use the username Rirez.

User avatar
Zamfir
I built a novelty castle, the irony was lost on some.
Posts: 7594
Joined: Wed Aug 27, 2008 2:43 pm UTC
Location: Nederland

Re: Why do online tutorials confuse you?

Postby Zamfir » Mon Dec 12, 2011 2:40 pm UTC

Steax wrote:actually, my closer friends who want to learn this stuff, so they're the perfect target audience too

That's good too, but make sure you get input from other experienced developers as well. Preferably people from a different environment than you. If you're serious about making this good, and not just another tutorial among many, you might want to find other people to work on the project together with you.

User avatar
Steax
SecondTalon's Goon Squad
Posts: 3038
Joined: Sat Jan 12, 2008 12:18 pm UTC

Re: Why do online tutorials confuse you?

Postby Steax » Mon Dec 12, 2011 3:13 pm UTC

We're working in a group of 5 writers, so we'll cross-read each other's, too. I agree, though - I'll try getting some more experienced developers to help. It's just kinda hard to find them, especially given the language barrier.

(I really hope I do this properly, because we're pretty much the first site of the kind for Indonesia, and we'll be setting a benchmark.)
In Minecraft, I use the username Rirez.

User avatar
Zamfir
I built a novelty castle, the irony was lost on some.
Posts: 7594
Joined: Wed Aug 27, 2008 2:43 pm UTC
Location: Nederland

Re: Why do online tutorials confuse you?

Postby Zamfir » Mon Dec 12, 2011 3:24 pm UTC

Ah, you're already working together with others, that's good.

Have you consider translating particularly good articles from English, as a start? There must be quite some authors willing to agree to that, if you give them appropriate credits.

User avatar
Steax
SecondTalon's Goon Squad
Posts: 3038
Joined: Sat Jan 12, 2008 12:18 pm UTC

Re: Why do online tutorials confuse you?

Postby Steax » Mon Dec 12, 2011 3:35 pm UTC

The original idea came about when a bunch of bloggers decided we need a central tutorial site localized for our country, to stop crappy developers from using "I suck at english" excuses. So yes, we're definitely working in a group, and trying to do it as professional as possible. We'll be sticking to a set of categories/topics, and will publish every tuesday and friday, with blog-like posts going in between. While the site is basically an online magazine of sorts, the set of basic tutorials will be an entirely different subdomain; we don't want them to be chronologically ordered or anything like that. Like many other good tutorial sites, we want the basic/beginner/low-level tutorials to be clear of as many distractions as possible.

More in-depth, topical, and temporal tutorials/articles go into the "magazine" main site, though. It's basically the method used at Video Copilot - a set of "basic training" tutorials set aside from weekly focused ones.

We're indeed starting with translated articles - mostly old ones with interesting insight, to balance out the more up-to-date tutorials. Many of them are A List Apart articles (since they allow translations explicitly, so no hoops to jump through), such as this one advocating CSS from 2000.
In Minecraft, I use the username Rirez.


Return to “Coding”

Who is online

Users browsing this forum: No registered users and 4 guests