bookmark_border

What makes a good tutorial?

Mohammad Shaddad,

I'm always thinking: What truly makes a good tutorial? What does it take to create an engaging tutorial that the reader would benefit from? A tutorial they would want to share with their friends and colleagues?

We sat down over a cup of coffee and came up with this list.

A topic that matters

The first is a well selected topic. The first decision point a reader faces when choosing whether to click to view your tutorial is based on the topic, which is inferred from the title. If the reader doesn't find the topic interesting, then the odds are, she will not click the link. So choose a topic carefully, choose an area you have the know-how in, and craft a well written title.

People usually look for help on the latest technology topics and trends. These are the areas where they are looking to build their expertise in, and don't have a lot of resources. Other topics already have a plentiful of resources. Still, you can re-write a classic and be a major hit.

Specific

Good tutorials focus on the subject at hand. They don't drift away between topics.

When you write your tutorial, focus on expanding on the title, don't drift away into supporting topics. Write a detailed deep-dive into a topic so readers stay engaged and focused. This allows you to bring out the best of your knowledge and a better, more effective writing.

If there are areas that require expanding on, use dedicated tutorials for them, and link, create your own Star Wars series.

Broken up

They have a structured outline. Start with a summary expanding on the topic at hand, giving the reader a rundown of what to expect in the tutorial and what she will be taking away from the tutorial. Make it exciting, and short, this is your elevator pitch to win the reader's heart and make them want to take the journey. This is usually a short paragraph, maybe a 100 - 150 words.

Once you have got the reader excited about the journey, start with breaking your outline into the steps needed to complete the journey. These are the multiple stops and the major attractions along the journey. Make them clear, concise and organized. Make it easy for the reader to come back to the tutorial and know where to continue or refresh on a step.

Once the reader have completed the journey, it's souvenir time. Give the reader a rundown of what she have accomplished, sum up what she learned, and throw in some additional links to where they can get extra resources for details on a supporting topic, or a next tutorial she can read to learn more.

Visual

Good tutorials take you on a journey, and a journey is not complete without scenery. Add visuals, whether these are screenshots of what to enter on the screen, or where to click, or whether these are supporting graphs/visuals that will help you get the point across. And don't forget to highlight or annotate your screenshots, it makes it clearer. You know the old saying: A Picture is worth a thousand words.

Easy going

A good tutorial feels like an over coffee chat with a friend.

Writing style is key when it comes to tutorials. They have a conversational tone, and make you feel like you are chatting with a friend and trying to hack something together. No one, and we do mean no one, likes a bossy, dry tutorial. We might sit through it and read it, but only if we had a deadline to make and boss nagging over it.

Keep your words simple, and don't use big, over-complicated words. Don't pull a Joey and abuse the thesaurus.





Written with passion

To quote Chandler from the Friends scene above: "Just write from here, your full-sized aortic pump".

The best tutorials are written with passion. When you choose a topic you are passionate about, it shows in your writing style, and the reader can sense it, and will be more engaged in the tutorial. If you are not into .NET, don't write about it just because .NET Core is all the craze right now; is it? really?!

People write because they are passionate about a topic and are passionate about helping people grow. Show us your passion.

Not everyone is a natural born writer. Some write with ease, some have to try a little harder to write. I am one of the latter. It takes passion and dedication to up your writing game. Keep writing, and you will get better with time. I usually draft and rewrite a couple of times, and I sleep on the last draft before I publish. You can share your tutorial with your friends before you publish, get their feedback and update if needed.

Hopefully, this short list will help us all get our tutorials to the next level. And if you have other tips to add, please share them below in the discussion section.

Keep writing and let us all learn.



generalwriting

What level is this content for?

We've all had our humble beginnings, it's our hard learned experiences that got us to master our code. We will all learn something sharing our knowledge, leave a legacy and write a post now.
create Write post

About the author


Mohammad Shaddad
Mohammad Shaddad

Mohammad is a technology consultant and entrepreneur with big passion for technology and living systems; aka software communities. He enjoys mentoring other programmers and entrepreneurs, as well as creating new things. Mohammad is the founder of @barmijly and @nafaqati. He currently spends his time between Amman.JO and Dubai.AE.