This is a guest post by David Pfahler and Stephan Bönnemann of

Total reading time: 3:57min (based on Alex)

When you try to learn a new programming language or work with a new framework for the first time you’re likely to google something along the lines of “How to …” or “framework X tutorial”. As a developer you might also be the one writing how-to articles for your own creations. If you’re interested in turning your 569-page long, textbook-style manual in to a golden asset of yours, please read on.

Your 20th century, worn out screencast series isn’t that fancy either…

Some users just get started with programming or using a framework (or whatever your product might be). Not everybody is a pro. For the rest of us tutorials are a low-barrier entry to your creation.
Furthermore, thinking about tutorials early on will force you to avoid complexity. For example, if you can’t explain a concept in simple terms, you should probably think about it again. By putting yourself in the shoes of your prospective customer you help yourself to create a better product in the end.

So how should an amazing tutorial look?

The idea behind most tutorials is to show the reader a step by step protocol of how you, the developer, would do it. However, what the user really wants is to learn, not to watch the presenter using his evil vim skills to confuse the overwhelmed newbie who is busy trying to get off the ground. One would learn way faster if she was live coding and seeing the results as she writes the code herself.
I’d love to see more editors in the browser used for this purpose. For example, the codecademy uses an in browser editor and console to teach programming to beginners.

Codecademy Screenshot

How to use multi media the right way

Screencasts are a popular tool when it comes to tutorials. However, they are not interactive, so the user can only watch but not try for herself unless she pauses the video and switches to a text editor, checks the results and repeats. Also, you can’t copy and paste from a screencast. We can do better.
Video can transport emotions. So I think it should be used for just that. How about a short introduction to the topic one is about to tackle? Just ten seconds of someone talking to you “face-to-face” make the whole experience more personal. Audio can do a great job at communicating a lot of content without requiring a lot of screen estate. Carrying on with the last example, the person who gives the introduction should also be the speaker of the tutorial. Additionally, text can help with copy & paste issues, hyperlinking to other resources such as the documentation, etc.

Positive feedback loops vs. frustration

Most tutorials that I encountered where quite frustrating. The reason being that there was no positive feedback loop supporting my will to learn more. For example, I never knew how long it will take to complete a certain tutorial. This sometimes leads to me not even starting because it gives me a psychological excuse.

“I probably won’t be able to complete it before lunch, anyways.”


“Ah nice! This is going to be done before lunch.”

So, in your tutorials please tell the user how much time she has to invest. As this forces you to think about the structure and length of your lessons, your whole tutorial will benefit.

The khan academy does a great job at keeping its students motivated with occasional achievement badges. People want to be rewarded when they take the effort to learn something new. Tutorials are a tool for just that. So please treat it like learning. Progress can be rewarded constantly for example with points or a virtual currency that one earns. I think we can learn a lot from games in regard to how they keep people engaged.

Khan Academy Screenshot

If you have some good examples, please let me know in the comments.


In the end the user is the reason for your creation, product or project. Thinking about your tutorials early on is a good way to ensure you’re producing something of value. Because your users are the ones who will ask you questions about your project, will buy your products (if they are for sale), submit pull-requests and talk about your creation in public, a great set of tutorials will benefit you the most.

Don’t spend your budget on a social media campaign run by an evil marketing firm. Spend it on your tutorials. It’s the best marketing there is.

codecademy: Nice editor in the browser. Positive feedback loop.
khan academy: Eleborate achievement system. Also, nice for improving your general knowledge.
knockoutJS: Editor in the browser, progress saved in localStorage and it can fix your code.
Try Haskell: Interactive console for learning/trying Haskell.
Layer Styles: Play around with the parameters and get an intuitive feeling for the css behind it. That’s the power of live editing.