Grrrrrrr! Yet another cycle of troubleshooting my broken code from a tutorial!

Is it me? Is it the tutorial? Is it my bad karma? How can I figure out what is wrong?

I AM LEARNING. HOW COULD I KNOW?

Does this sound familiar? How many times have you beat your head against the wall like this? You may think you have lost count due the brain damage from all that head-bashing, but you have lost count because this problem is everywhere.

Most tutorials become quickly outdated, because technology moves at a very fast pace, and most authors don’t have the time to revisit their tutorials to make sure the code still works. It’s easy to say (and I certainly do say) “They should just find the time to do that!”–but like many things in the real world of busy people, that is easier said than done.

So what is the solution?

There is no silver bullet. Perhaps something like ChatGPT (running in the background to update the code examples) will be a good solution some day, but those AI models are usually a couple of language/framework releases behind, so that idea is not a viable solution just yet.

Until then, we need to find a way to make tutorials actually teach instead of driving learners crazy.

Enter the DOtorial

When we find an article that promises to teach us something, the last thing we need is to spin our wheels trying to figure out who knows less: The tutorial or us.

• We need that content to be correct, up-to-date and clear. We need to read, learn quickly and move on, because we have things to DO with that knowledge.

DOtorials are designed–and continuously updated–so they meet these requirements.

But how can this be?

That’s a sensible question. The Internet is littered with examples of out-of-date content, so keeping tutorials up-to-date must be pretty hard, correct?

• Sure, it’s hard. Lots of things are hard, and they don’t get solved until someone insists on asking a different question:

Why should we continue to tolerate this?

To paraphrase someone famous:

We aren’t going to take this any more!

Dotorial Vision

Our vision here is to create an article publishing solution that includes ongoing curation of the tutorial code (and accompanying narrative) so that as the code becomes out of date, the “curation process” of the solution updates the example code and its explanation as required.

• BIG IDEA: Ideally, this curation process will evolve to enable the reader to select the language/framework version, then see the code examples and explanation adjust to match that version.
• CORE FEATURE: LiveBook-like execution in the article to see that the example code actually works.

This all may sound Quixotic, and it won’t be easy, but there are emerging technologies that make this feasible.

The Elixirized team is committed to making this a reality.