Learn to Code via Tutorials on Repl.it

← Back to all posts
Writing a Good Tutorial on Learn
Zavexeon (633)

What's this?

A tutorial, on making tutorials? This is some meta-level stuff right here. Anyways, lets cut to the chase: first, what exactly makes a good tutorial?


Attributes of a Good Tutorial:

Clear Purpose

The point of your tutorial should be direct. For example:

This tutorial will show you how to set up an Express server in node.js!

Nice and succinct.

Well Organized

A good tutorial is tidy and appealing to look at. Key components are broken down into sections and if large enough, preferably stylized with markdown.

Original

Make sure before creating a new tutorial that it doesn't exist yet. Use that search bar! Unless your tutorial provides a significant increase of depth compared to the original, creating it is redundant.

Easy To Follow

All tutorials should be similar to reading instructions. It needs to be clear, and easy for the reader to follow. Explain things in sufficient depth, and assume that the reader knows nothing of the topic.

In-depth

Don't post a tutorial that simply tells you how to open a file in Python. Instead, write a tutorial on advanced file manipulation in Python. Your tutorial should not be something somebody can easily reference from some sort of documentation in 5 seconds. It should be meaningful and provide the reader with something to think about.

Well Written

The tutorial should be written in English, have decent grammar and spelling, and capitalization and punctuation. We're not asking you to write a college essay, but we're not asking for a quick text to your friend, either!

Helpful

The whole purpose of a tutorial is to help someone do something. A good tutorial should provide aid to the reader, and they should walk away with knowledge they can apply to something

Examples

Examples are a crucial part of any tutorial. It helps the reader understand what you're teaching and how it can be applied. If you're providing code examples, links to repls or embedded code using backtick markdown is greatly appreciated!

Existing Good Tutorials

There are plenty of great examples of good tutorials here on repl.it. Look through some of these, and study them and why they're great!


Writing a Tutorial:

Alright, now we know what makes a good tutorial; however, we don't know how to make one. Well, lucky for you, I've broken it down into a few steps!

1. Choose a topic!

  • Like mentioned above, your topic should be original and in-depth. If you're having trouble thinking of a topic, ask yourself, what do people struggle to do?

2. Research!

  • Before you can teach others, you must learn yourself. Research the topic until you have a good understanding of it and feel like you can thoroughly teach another about it.

3. Write it!

  • Start writing up your tutorial. Write it like you're explaining something to them, which, well, is what you're doing. Break it down into digestible, bite-size chunks and write a little bit on each of those chunks. Make sure to specify if they require any background knowledge, and if so, provide a resource for it. And remember, you can never have too many examples!

4. Publish it!

  • This is the easiest part. Click that green Submit button and let everyone on repl.it see the glorious tutorial you made!

5. Update It!

  • Afters posting you may notice you seemed a bit vague in one section of your tutorial, or you spelled something incorrectly, or your example is broken, or maybe you just wanted to add some more. That's okay! Just click that edit button, and do whatever you feel is necessary.

6. Answer Questions!

  • It's not uncommon to receive questions on your tutorial. If you do, try making your best effort into answering it, and if you're unable, link a resource for the person who asked.

And there you have it, a tutorial on making tutorials. Hope this helps you all, I can't wait to see the awesome tutorials you guys and gals come up with!

One Last Thing

This is about what makes a good tutorial. What makes a great tutorial has everything mentioned here, but also includes this at the end:

Guess that makes this a great tutorial, then.

Commentshotnewtop
Zoei (4)

Very cool, there aren't many well done tutorials out there in the case of specifics and research, so some decent points were made. Side note is I'm not going to be on due to Thanksgiving break, but good job. And question, why should tutorials be written in English? There are some German speakers out there I bet 😏

Zavexeon (633)

@Zoei A majority of repl.it users are English speaking.

eankeen (810)

this guide is pretty much on point - i would add that it is also good to reply to people that have comments or questions about your tutorial. :P