How to write a coding tutorial
September 15, 2019
Technical tutorials are integral to learning how to code and build software. I’m sure you’ve benefited a ton from others’ tutorials that make you a better programmer and enable you to do things you couldn’t do before.
Reading tutorials is great, but there are plenty of benefits of writing your own…
- forces 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
- helps out folks learning the same thing as you
- gets your name out there in the community
- requires that you understand what you’re doing/building enough to be able to explain it to somebody else
- shows your competency, communication skills, etc. to potential employers/collaborators
- Pick a tech/tool/topic you want to learn and write about
- Develop a basic understanding of your tutorial’s subject matter
- Start experimenting with some code
- Build the tutorial’s project
- Rebuild from scratch while writing an outline of the tutorial
- Turn your outline into a rough draft
- Spruce up the rough draft
- Walk through the tutorial like you’re the reader
Obviously this ain’t the only way to go about crafting a tutorial - but it’s helped me write a few and at least can get the juices flowing for you to find your own style/process.
Quick thing before you dive in!
I’m sure I’m missing stuff here - so I created a GitHub repo so that this process can be open source and improve over time.
Here’s the link 👉 https://github.com/ryanjyost/how-to-write-a-coding-tutorial
Tutorial writing process
1. Pick a tech/tool/topic you want to learn and write about
There are so many ways to come across potential subjects - here’s a few.
- What tech is being used at your work that you’re not super experienced with?
- What’s a buzzword you keep hearing but haven’t explore yet?
- Do you keep seeing a certain skill in job descriptions that you don’t have yet?
- Did you recently struggle through learning something and wish there had been a tutorial to help?
2. Develop a basic understanding of your tutorial’s subject matter
- Keep notes of things you’ll want to bring up in your tutorial.
- Bookmark useful articles, other tutorials, videos, docs, etc. to easily reference and include them as links in the final piece.
- Google and official documentation are your friends here.
- Don’t spend too much time here going down rabbit holes. Learning more is great, but you eventually gotta move on - you’ll learn plenty in the next steps.
3. Start experimenting with some code
- Initialize a basic boilerplate project/environment so you can start writing code.
- This is a time to play with the stuff you’re learning and eventually going to write about.
- No need for structure, clean code, etc. Just try to make stuff happen.
- As you get more comfortable, start to think about how the stuff you’re coding can be structured to showcase the important aspects of your subject in the form of a small app/project.
- If you run into anything not obvious or worth noting while getting started, jot it down - it can be a helpful tip in your tutorial.
4. Build the tutorial’s project
- Leverage your experience from the previous step.
- This is arguably the most important part of the process - it’s the meat of what your audience will have to learn about the subject matter.
- While there are certainly some more complex tutorials, try to keep things as simple as possible - overly complex apps could scare away your audience. My first tutorial definitely suffered from this…
There’s no right way to build a tutorial project, but here are some characteristics I’d say are beneficial…
- It’s the simplest way to get your points/subject across.
- It’s very easy to set up - no need to install crazy stuff or get lost in configuration. Boilerplates like create-react-app are perfect for starting a tutorial, b/c everyone who writes React is familiar with it, or will be quickly.
- It has clean, organized code.
- It has some real-world theme for the functionality, versus abstract stuff like
bar. Don’t get too fancy or complicated, either.
5. Rebuild from scratch while writing an outline of the tutorial
- The goal here is to start organizing everything you’ve done so far into a logical, step-by-step order that will represent the linear progression of your tutorial.
- Try to rebuild the project in as structured and progressive a way as possible, so your tutorial will flow nicely and not confuse the reader.
- Save code snippets as you go through rebuilding the project, again trying to introduce new code in bite-size, helpful increments.
6. Turn your outline into a rough draft
- Basically, you’ll want to convert the bullet-point outline of your tutorial into a long-form version with full-sentence instructions and code snippets included where applicable.
- Don’t worry about adding explanations of concepts or expressive writing - a boring, no-frills set of instructions will suffice for this step.
- When done with this step, you should be able to follow your tutorial and build the example project.
7. Spruce up the rough draft
- Add in any explanations, quotes, humor, flair, nuance, etc. that you want - here you’re polishing up the rough draft.
- Usually it’s nice to start a tutorial with some context for the reader - who this tutorial is for, why you are writing it, any prerequisite knowledge needed, etc.
- This is also a good time to add any links you’ve found helpful - they can be inline, or compiled at the beginning or end for further reading.
8. Walk through the tutorial like you’re the reader
- This is like doing QA for your tutorial.
- Follow the tutorial as though you have no prior knowledge/experience with the material. Try to uncover any areas or steps where a reader could be confused - you might be taking a certain piece of info for granted!
- Revise, reorder, fix, etc. as you come across issues.
Could be your own blog, on Medium, in a publication that accepts outside submissions - just as long as it gets out there in the world for folks to benefit from.