Writing a Good Tutorial on Learn
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:
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.
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.
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.
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.
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!
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 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!
- A Quick Guide to Repl.it Talk Markdown
- Creating a VueJS app: A tutorial for beginners
- 3D graphics, a beginners mind.
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?
- 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.