└── README.md /README.md: -------------------------------------------------------------------------------- 1 | Read the original blog post here 👉 https://ryanjyost.com/how-to-write-a-coding-tutorial 2 | 3 | ## TL;DR 4 | 1. Pick a tech/tool/topic you want to learn and write about 5 | 2. Develop a basic understanding of your tutorial’s subject matter 6 | 3. Start experimenting with some code 7 | 4. Build the tutorial’s project 8 | 5. Rebuild from scratch while writing an outline of the tutorial 9 | 6. Turn your outline into a rough draft 10 | 7. Spruce up the rough draft 11 | 8. Walk through the tutorial like you’re the reader 12 | 9. Publish! 13 | 14 | ## Tutorial writing process 15 | ### 1. Pick a tech/tool/topic you want to learn and write about 16 | There are so many ways to come across potential subjects - here's a few. 17 | 1. What tech is being used at your work that you're not super experienced with? 18 | 2. What's a buzzword you keep hearing but haven't explore yet? 19 | 3. Do you keep seeing a certain skill in job descriptions that you don't have yet? 20 | 4. Did you recently struggle through learning something and wish there had been a tutorial to help? 21 | 22 | ### 2. Develop a basic understanding of your tutorial's subject matter 23 | - Keep notes of things you'll want to bring up in your tutorial. 24 | - Bookmark useful articles, other tutorials, videos, docs, etc. to easily reference and include them as links in the final piece. 25 | - Google and official documentation are your friends here. 26 | - Don't spend too much time here going down rabbit holes. Learning more is great, but you eventually gotta move on - 27 | you'll learn plenty in the next steps. 28 | 29 | ### 3. Start experimenting with some code 30 | - Initialize a basic boilerplate project/environment so you can start writing code. 31 | - This is a time to play with the stuff you're learning and eventually going to write about. 32 | - No need for structure, clean code, etc. Just try to make stuff happen. 33 | - As you get more comfortable, start to think about how the stuff you're coding can be structured to showcase the 34 | important aspects of your subject in the form of a small app/project. 35 | - If you run into anything not obvious or worth noting while getting started, jot it down - it can be a helpful tip 36 | in your tutorial. 37 | 38 | ### 4. Build the tutorial's project 39 | - Leverage your experience from the previous step. 40 | - This is arguably the most important part of the process - it's the meat of what your audience will have to learn 41 | about the subject matter. 42 | - While there are certainly some more complex tutorials, try to keep things as simple as possible - overly complex 43 | apps could scare away your audience. 44 | - There's no right way to build a tutorial project, but here are some characteristics I'd say are beneficial... 45 | 1. It's the simplest way to get your points/subject across. 46 | 2. It's very easy to set up - no need to install crazy stuff or get lost in configuration. Boilerplates like 47 | create-react-app are perfect for starting a tutorial, b/c everyone who writes React is familiar with it, or will 48 | be quickly. 49 | 3. It has clean, organized code. 50 | 4. It has some real-world theme for the functionality, versus abstract stuff like `foo` and `bar`. Don't get 51 | too fancy or complicated, either. 52 | 53 | ### 5. Rebuild from scratch while writing an outline of the tutorial 54 | - The goal here is to start organizing everything you've done so far into a logical, step-by-step order that will 55 | represent the linear progression of your tutorial. 56 | - Try to rebuild the project in as structured and progressive a way as possible, so your tutorial will flow nicely and 57 | not confuse the reader. 58 | - Save code snippets as you go through rebuilding the project, again trying to introduce new code in bite-size, helpful 59 | increments. 60 | 61 | ### 6. Turn your outline into a rough draft 62 | - Basically, you'll want to convert the bullet-point outline of your tutorial into a long-form version with 63 | full-sentence instructions and code snippets included where applicable. 64 | - Don't worry about adding explanations of concepts or expressive writing - a boring, no-frills set of 65 | instructions will suffice for this step. 66 | - When done with this step, you should be able to follow your tutorial and build the example project. 67 | 68 | ### 7. Spruce up the rough draft 69 | - Add in any explanations, quotes, humor, flair, nuance, etc. that you want - here you're polishing up the rough draft. 70 | - Usually it's nice to start a tutorial with some context for the reader - who this tutorial is for, why you are 71 | writing it, any prerequisite knowledge needed, etc. 72 | - This is also a good time to add any links you've found helpful - they can be inline, or compiled at the beginning 73 | or end for further reading. 74 | 75 | ### 8. Walk through the tutorial like you're the reader 76 | - This is like doing QA for your tutorial. 77 | - Follow the tutorial as though you have no prior knowledge/experience with the material. Try to uncover any areas or 78 | steps where a reader could be confused - you might be taking a certain piece of info for granted! 79 | - Revise, reorder, fix, etc. as you come across issues. 80 | 81 | ### 9. Publish! 82 | Could be your own blog, on Medium, in a publication that accepts outside submissions - just as long as it gets out 83 | there in the world for folks to benefit from. 84 | 85 | --------------------------------------------------------------------------------