Super Short Tutorials Failure

Posted: May 8, 2018 | | Categories: Miscellaneous

I subscribe to several of the few remaining technical magazines in the technology and Maker spaces.  I've noticed recently that these magazines publish really, really short tutorials. I imagine they do this in order to deliver more articles in a single publication, but the end result is that these tutorials are relatively useless from a learning standpoint.

Now, don't get me wrong, there are a lot of tutorials in these magazines.

My issue is that, for many of them, they set an arbitrary length limitation (usually 2 or 4 pages) for the article, no matter how complicated the topic. When this happens, the writer has to deliberately omit a lot of details about what's going on with the project.

I've found that these short articles have the following issues:

• Abrupt introduction - for many of the articles, the author skips completely describing what it is you're building. If you're several paragraphs into a tutorial and you don't yet know exactly what you're learning, is it your fault, or the author's?
• Commands without reason - so many times you'll be working through a Linux tutorial and you'll be instructed to execute certain terminal commands without any explanation of why you're executing these commands. Without any information about why you're doing certain steps, how exactly are you learning?
• Missing troubleshooting information - great, the author's told you what command to execute and is already off describing the next step. What if the command doesn't work? What if the output you see is different than what the author tells you you should see? How exactly are you going to be able to complete the project? With every step should come a simple but useful description of what could go wrong. If it works, the reader can quickly skip ahead to the next step. If it doesn't work, the reader has what he or she needs to recover from encountered errors.
• Forced images - One magazine I've written for demanded a specific number of images for every page of content. I get it, eye candy makes the articles more pleasant to look at, and breaks up the text. What happens if you're describing something that doesn't have images (like programming or language concepts)? This causes many authors to make something up, create images just so you'll have them to look at. The best example of this for me is Raspberry Pi tutorials where authors include screenshots of terminal windows - which are completely illegible on the printed page. Publisher requirement met, but user value not met.
• If the author's any good at organizing his or her thoughts and writing, and you're any good at following instructions, then chances are you'll finish the process with a discernible result. However, will you have actually learned anything?  The instructions work for the specific hardware and/or software setup, but will you be able to apply what you did to other scenarios? I doubt it.

These authors are working for very little, or no money, but are trying to share their knowledge and experience. I love that! That's one reason why open source software is so spectacular. We need to be vocal about our wishes here. Let us learn as much as possible from these author's great work. Demand that these magazines relinquish control and let the writers write complete tutorials. During the editing process, trim out the extra and unneeded stuff, but let the complete description of the process be free!

Photo by Charisse Kenion on Unsplash

Next Post: SiteLock's Deceptive Sales Tactics

Previous Post: Pug and JavaScript Functions

Header image: Photo by Marcos Paulo Prado on Unsplash