Writing Software Tutorials for Beginners - 10 Tips, Tricks, and Rules I Follow
My writing journey began in 2020, and over the years, I have refined my strategy and learned many different techniques and writing styles. I started by writing many articles for free on my blogs and then moved on to writing many articles for various clients as my knowledge and experience in this industry grew.
Taking all of this into account, I have put together a list of 10 tips and tricks that I have been following. These have allowed me to create consistently good articles over the years, which are often shared on social media and help other people in the tech industry learn.
1. Write like you are a beginner
It's a good strategy to write your articles as if you are reading them for the first time and have no idea what they are about. This can make the content much more uncomplicated to digest and understand. I aim to limit the time the reader spends doing external Google searches because they don't understand some of the concepts you are discussing.
2. Explain every code block
Writing a code summary or explaining what a code block is doing is extremely helpful and a great way to avoid that copy-and-paste situation where you are copying code and following a tutorial. Still, you don't really understand what that code is doing. This in itself can lead to "tutorial hell".
3. Create run scripts
If you're creating a tutorial from scratch, the reader will likely have to go through the entire build stage. It is far too tedious to have the reader manually cd into this folder and then create all of the files one by one. Instead, I prefer to make a run script that the reader can copy and paste into their terminal, run, and then it will set up the whole project for them. Then, all that is left is the codebase.
4. Put the codebase on GitHub
Putting the complete codebase on GitHub means that the reader has access to the entire code right from the start and can see the entire project. This saves a whole lot of time, and it means that the reader does not have to go step by step through the tutorial themselves if they don't want to or don't have the time.
5. Show a screenshot of the final application
People want to know what they are building, so if you have a screenshot of the final application—or, better yet, screenshots of every page or screen—that helps the reader visualise what they are making.
6. Have a link to the live application online
When the final application is deployed online, the reader can watch the live demo to get a feel for what they will be building. This can be even better than looking at static screenshots.
7. Write the article in Markdown if you can
Markdown is the best language for writing articles. The language is powerful, and you can easily publish the article online on many platforms, including GitHub, without having to modify any of the code. However, if you have clients, some might prefer that you write in Microsoft Word. If it's a text-based article, then it's not a big issue; however, if you have lots of code blocks, then writing them in a Word document is not as convenient because of the formatting and text highlighting issues that arise.
8. Check spellchecking and grammar
When writing, try to be professional. Double-check your spelling and grammar, and proofread your work. I like to use Grammarly because it is excellent at cleaning up early drafts and enhancing wording so the writing flows better.
9. Show the project structure
Being able to see the project structure makes it far easier to understand the architecture and how everything works. Files, folders and structure can be easily outlined in a nice overview.
10. Use images, charts or infographics
Make your article as beautiful as possible if you can. Include images to show the application or animated gifs to bring some life to the piece that the reader is reading. Charts can help when explaining something related to data, and infographics and other diagrams can break down and explain complex concepts.
Stay up to date with tech, programming, productivity, and AI
If you enjoyed these articles, connect and follow me across social media, where I share content related to all of these topics 🔥
