ryanjyost / how-to-write-a-coding-tutorial

A step-by-step process that will make it easy to crank out technical coding tutorials.

Read the original blog post here 👉 https://ryanjyost.com/how-to-write-a-coding-tutorial

TL;DR

1. Pick a tech/tool/topic you want to learn and write about
2. Develop a basic understanding of your tutorial’s subject matter
3. Start experimenting with some code
4. Build the tutorial’s project
5. Rebuild from scratch while writing an outline of the tutorial
6. Turn your outline into a rough draft
7. Spruce up the rough draft
8. Walk through the tutorial like you’re the reader
9. Publish!

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.

1. What tech is being used at your work that you're not super experienced with?
2. What's a buzzword you keep hearing but haven't explore yet?
3. Do you keep seeing a certain skill in job descriptions that you don't have yet?
4. 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.
• There's no right way to build a tutorial project, but here are some characteristics I'd say are beneficial...
  1. It's the simplest way to get your points/subject across.
  2. 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.
  3. It has clean, organized code.
  4. It has some real-world theme for the functionality, versus abstract stuff like foo and 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.

9. Publish!

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.