The Curse of the Magical Tutorial

Have you ever read a tutorial about something that you are new to, and really need to get into the subject quickly, just to discover that there is an essential piece of information missing? Yup, happens to me all the time...

Okay, to be fair not really all the time but unfortunately still too often. Especially when I'm scavenging the interweb for some crucial information or instructions about how to get started with technology X, how to use product Y efficiently, or to solve problem Z in a sustainable manner for good.

Writing is not for the faint of heart

Writing is a tough trade, and even more in regards to writing a tutorial. Not to mention a complete tutorial. I understand that a lot of time and energy goes into an article by the originating author. But please try to envision the point of view of your reader, too.

That's one small step for [a] man, one giant leap for mankind. – Neil Armstrong

The reader of a tutorial is not as familiar with the subject as you, the writer, might be, and this is something that should be taken into consideration before hitting that weird Publish button. As a reader, having to deal with an incomplete tutorial - or magical tutorial as I like to call them - is utterly frustrating for several reasons.

Unfamiliarity with the subject

First of all, your reader is probably new to the domain hence reading your article about it. With this comes a good chunk of insecurity and lack of (background) knowledge to make an informed decision about bits and pieces that are described in the tutorial. At this stage a reader fully trusts in the author's expertise on the subject.

Courtesy of Van Oktop

At least for me, it is quite annoying to follow each particular step in a tutorial meticulously only to realise at a certain stage that the progress does a magical jump from A to B - without providing any further details about what just happened...

Add those small details

Second, review your content before you publish it. And this should include peer reviewing. Yes, reach out to your life partner, colleague at work, or perhaps members from your community and ask them kindly for their feedback. Perhaps you might even have an editor that not only proof-reads your content but also checks your instructions or code samples. Having an editorial team is something absolutely normal in regards to publishing a book, so why shouldn't this apply to posting a blog article, too?

While writing a tutorial I'm trying to change my own point of view. Meaning, I virtually take of the author's cap and put on the newbie's hat. Then I follow my own instructions each single step. If there are snippets of source code I create a new project and copy and paste the code to see what's missing. In case of commands on the CLI I open the terminal and I run the statements to see whether it works as expected and to compare the output to what I might have documented.

Additionally, I learned something from John O'Nolan, the creator of the Ghost blogging platform:

Write drunk; edit sober – Ernest Hemingway

And as John stated it - Regardless of whether or not he ever actually said it (we're sure you'll let us know in the comments), the notion is a good one. - I have to agree.

Give your content some time to settle... in your mind.
I usually let my articles rest at least over night or sometimes give them several days before I make them public. This changes my perception of the tutorial as I'm not too deep into the writing process anymore and my focus is less narrowed down to accidentally overlook those important small details.

Provide additional material

Third and this clearly depends on the nature of your tutorial, consider to provide your source material to your readers.

For example, in case of an article on software development either offer an option to download the whole stuff or link to a public source code repository. Personally, I would prefer latter as this opens up the possibility that your readers can document an issue or even send you a pull request with changes and improvements to your code base.

One single article or a series of articles?

Depending on the amount of information or the complexity of the domain it might be a positive notion to split a tutorial into several chunks, then give them a specific order and interlink them. It's like chapters in a book; break it down for your readers and give them a better experience to follow your instructions.

Perhaps you might be interested to check out my series of articles on using IPv6 protocol in Linux as an example, which is broken down into four pieces:

Each single article can stand on its own but it is the combination of all in the series to give you the complete picture and result you might be looking for.

It's not all about pixie dust

Writing an article on a certain topic is quite an effort; sometimes hard work, and not at all some kind of voodoo or magical pixie dust. A tutorial is also a way to document your own experience about dealing with a specific problem and most likely how to solve it. Remind yourself about how you started and empathise the pain your reader might encounter while reading your content.

As soon as you know the solution the whole problem doesn't appear to be that complicated anymore. Keep this in mind while writing and reviewing your work. If you cannot explain it in simple terms it is either not fully understood or still to complex and needs more attention to those small details. Don't skip anything; instead give it some more time...

What are your thoughts on magical tutorials? Please leave a comment to elaborate on this topic. Thanks.

Cover image courtesy of Jason Leung