Technical tutorials are an integral part of learning to code and build software. I’m sure you’ve benefited tremendously from tutorials from other people who make you a better programmer and let you do things you couldn’t have done before.
Reading tutorials is great, but there are many benefits to writing you…
- requires you to build something (small and simple) related to what you want to learn, which can be a stepping stone to a more complex portfolio project
- help people who are learning the same things as you
- make your name known to the community
- it requires you to understand enough what you are doing / building to be able to explain it to someone else
- show off your skills, communication skills, etc. to potential employers / collaborators
The steps to look out for
- Pick a technology / tool / topic you want to learn and write about
- Develop a basic understanding of the topic of your tutorial
- Start experimenting with a code
- Build the tutorial’s project
- Rebuild from scratch while you write a plan
- Turn your plan into a draft
- Improve the draft
- Follow the tutorial as if you were the reader
- To publish!
Process of writing the tutorial
1. Pick a technology / tool / topic you want to learn and write about
There are so many ways to meet potential subjects, here are just a few. What technology is used in your work that you do not have a lot of experience with? What’s the buzzword you keep hearing but haven’t explored yet? Do you still see skills in job descriptions that you don’t yet have? Have you had a hard time learning something lately and wish there was a tutorial to help you?
2. Develop a basic understanding of your tutorial subject
Take note of the things you will want to mention in your tutorial. Bookmark useful articles, other tutorials, videos, documents, etc. for easy reference and include them as a link in the final piece. Google and the official documentation are your friends here. Don’t spend too much time here walking down rabbit holes. Learning more is good, but in the end, you will have to move on, you will learn a lot in the next steps.
3. Start experimenting with code
Initialize a basic standard project/environment so that you can start coding. Now is the time to play with the things you learn and will eventually write about. No need for structure, clean code, etc. Just try to shake things up. When you feel more comfortable, start thinking about how the things you code can be structured to show the important aspects of your topic in the form of a small app/project. for starters, writing it down can be a useful hint in your tutorial.
4. Build the tutorial’s project
Build on your experience from the previous step. This is probably the most important part of the process, it is the flesh of what your audience will need to learn about the subject. While there are definitely more complex tutorials out there, try to keep things as simple as possible. Overly complex applications could frighten your audience.
My first tutorial definitely suffered …
There is no right way to build a tutorial project, but here are some features that I would say are useful …
This is the easiest way to get your points/topic. set up, no need to install crazy stuff or get lost in setup. License plates like Creatoreactapp are great for starting a tutorial, b / c anyone who writes React knows this, or will quickly be. It is a clean and organized code.
It has a real-world theme for functionality, as opposed to abstract things like foo and bar. Don’t be too fancy or complicated, either.
5. Rebuild from scratch as you write a draft tutorial
The goal here is to start organizing everything you’ve done so far in a logical, step-by-step order that will represent the linear progression of your tutorial. Try to rebuild the project in the most structured and progressive way possible, so that your tutorial runs smoothly and does not disturb the reader. Save the code snippets as you rebuild the project, again trying to introduce the new code in small, useful increments.
6. Turn your outline into a rough draft
Basically, you’ll want to convert your tutorial chip model to a long version with full instructions and code snippets included where applicable. Not worrying about adding concept explanations or expressively writing a boring and sane instruction set will suffice for this step. After completing this step, you should be able to complete the tutorial and create the sample project.
7. Improve the final output
Add any explanation, quote, humor, style, nuance, etc. you want here you perfect the project. It’s usually nice to start a tutorial with some context for the reader this tutorial is for, why you are writing it, the prerequisite knowledge needed, etc. It’s also a good time to add any links you have found useful which may be online or filled in at the beginning or end for further reading.
8. Be the reader
It’s like doing QA for your tutorial. Follow the tutorial as if you have no prior knowledge/experience with the hardware. Try to find areas or passages where a reader might be confused, you might take some information for granted! Revise, reorganize, correct, etc. As you run into problems.
9. Release to your audience
It could be your blog, on Medium, in a post that accepts outside contributions as long as it goes out into the world for people to benefit.