Sunday, December 31, 2017

Rules to make good training material

In the last 10 months I have been stuffing myself night and days, weekend and holidays, with training. Most of that training was decent, some excellent, some really appalling. What makes a material "excellent"?

a) the trainee must be able to reproduce the exercise on his own. So training material must start with detailed instructions on how to setup an environment. Preferably on Linux, please avoid Windows as a testing platform. No blablabla, just installation scripts and links to pre-built VMs or Docker images.

b) all code used in example must be available on Github, under the form of a complete, buildable, working example. Avoid by all means incomplete snippets of code. Instructions on how to setup the environment should be provided in a complete A-Z form, if possible with most common troubleshooting scenarios available.

c) theory and practice must go hand-in-hand. Avoid lengthy all-encompassing introductions teaching the history of humanity from Adam and Eve. Must of us are just interested on getting some technology to work and play a little with it. Every new concept should IMMEDIATELY exemplified with a simple experiment.

d) avoid complex examples with lot of business logic. Keep it simply, carve your examples in order to highlight the single concept you are talking about.

e) videos are great, but please avoid slides, unless each slide is accompanied by a real-life example. Don't talk more than 3 minutes, you should just show examples and illustrate code, clearly pointing out the new stuff. It's also great when one is shown the relevant official documentation together with the example. Evidencing code and documentation with a mouse selection also helps, so as the viewer can easily focus on the sensitive stuff.

f) by all means, avoid telling us about yourself, how good you are and how you spend your leisure time - unless you do something really valuable like protecting nature, but most NERDS don't care about nature, life or anything which is not IT-related. You are just a NERD, we don't care about your nerdy life, spent serving the interests of corporations. If you want to help humanity, just deliver clear, crisp, focused training. Be humble, be focused, talk less, show more.

g) avoid writing complex code during the tutorial. Watching someone typing code is painfully boring and big waste of time when things go wrong and time is wasted fixing the issue. Write your code in advance, put it in github and during the presentation just quickly illustrate it.

h) avoid making long bullet list like this one hahaha

No comments: